1X11DOCKER(1) General Commands Manual X11DOCKER(1)
2
6 x11docker - Run GUI applications and desktop environments in containers
7
11 To run a container on a new X server:
12 x11docker [OPTIONS] IMAGE [COMMAND]
14 x11docker [OPTIONS] -- IMAGE [COMMAND [ARGS ...]]
16 x11docker [OPTIONS] -- [CUSTOM_RUN_OPTIONS] -- IMAGE [COMMAND [ARGS
18 ...]]
19 To run a host application on a new X server:
21 x11docker [OPTIONS] --backend=host -- COMMAND [ARGS ...]
23
26 Runs GUI applications and desktop environments in containers. Supports
27 docker, podman, and (experimental) nerdctl. Can run X servers from
28 host or in containers of image x11docker/xserver. Can also provide X
29 servers to host applications. x11docker always runs a fresh container
30 from image and discards it afterwards.
31 Optional features:
35 * GPU hardware acceleration
36 * Sound with pulseaudio or ALSA
37 * Clipboard sharing
38 * Printer access
39 * Webcam access
40 * Persistent home folder
41 * Wayland support
42 * Language locale creation
43 * Several init systems and DBus in container
44 * Support of several container runtimes and backends
45 Focus on security:
48 * Avoids X security leaks using additional X servers.
49 * Container user is same as host user to avoid root in con‐
50 tainer.
51 * Restricts container capabilities to bare minimum.
52 x11docker sets up an unprivileged container user with password
54 x11docker and restricts container capabilities. Some applications might
55 behave different than with a regular docker|podman run command due to
56 these security restrictions. Achieve a less restricted setup with
57 --cap-default or --sudouser.
58
62 Short options do not accept arguments.
63 --help Display this message and exit.
65 --license
67 Show license of x11docker (MIT) and exit.
68 --version
70 Show x11docker version and exit.
71 Basic settings
75 --backend=docker|podman|nerdctl|host
76 Container backend to use, or host for no container.
77 -d, --desktop
79 Indicate a desktop environment in image.
80 -i, --interactive
82 Run with an interactive tty to allow shell commands.
83 --rootless [=yes|no]
85 Use (or disallow) rootless backend. Default behaviour without
86 option --rootless:
87 --backend=docker: rootful unless environment variable
88 DOCKER_HOST is set.
89 --backend=podman: rootless except started as root.
90 --backend=nerdctl: rootless except started as root
91 --xc [=yes|no|BACKEND]
93 Run X server in container of image x11docker/xserver. BACKEND
94 can specify one of docker|podman|nerdctl.
95 --xonly
97 Only start an empty X server.
98 Host integration
102 --alsa [=ALSA_CARD]
103 Sound with ALSA. You can define a desired sound card with
104 ALSA_CARD. List of available sound cards: aplay -l
105 -c, --clipboard [=yes|no|oneway|superv|altv] Share clipboard with host.
107 Possible arguments:
108 yes Share clipboard in both directions. Includes mid‐
109 dle-mouse-click selection.
110 oneway Copy clipboard from container to host only. Includes
111 middle-mouse-click selection.
112 superv Keys [SUPER][v] copy clipboard from host to container.
113 Does not copy middle-mouse-click to container. Otherwise same as
114 oneway.
115 altv Same as superv but using keys [ALT][v].
116 no Do not share clipboard.
117 -g, --gpu [=yes|no|iglx|virgl] GPU access for hardware accelerated
119 OpenGL.
120 Works best with open source drivers on host and in image. For
121 closed source nvidia drivers regard terminal output. Direct
122 rendering supported by few X server options only.
123 iglx enables indirect rendering (--xorg only).
124 virgl allows GPU access for all X servers, but with limited per‐
125 formance and with --xc only.
126 -I, --network [=NET]
128 Allow internet access. (i.e. allow Docker default.) For op‐
129 tional argument NET see Docker documentation of docker run op‐
130 tion --network. Docker default is bridge.
131 -l, --lang [=LOCALE]
133 Set language variable LANG=LOCALE in container. Without arg LO‐
134 CALE host variable --lang=$LANG is used. If LOCALE is missing
135 in image, x11docker generates it with localedef in container
136 (needs locales package). Examples for LOCALE: ru, en, de,
137 zh_CN, cz, fr, fr_BE.
138 -P, --printer [=MODE] Share host printers through cups server.
140 Optional MODE can be socket or tcp. Default: socket
141 -p, --pulseaudio [=MODE]
143 Sound with pulseaudio. Needs pulseaudio on host and in image.
144 Optional arg MODE can be socket, tcp or host. tcp mode needs
145 network access with --network.
146 --webcam
148 Share host webcam device files.
149 Shared host folders or volumes
153 -m, --home [=ARG]
154 Create a persistent HOME folder for data storage. Default: Uses
155 ~/.local/share/x11docker/IMAGENAME. ARG can be another host
156 folder or a volume. (~/.local/share/x11docker has a softlink to
157 ~/x11docker.) (Use --homebasedir to change this base storage
158 folder.)
159 --share=ARG
161 Share host file or folder ARG. Read-only with ARG:ro . Device
162 files in /dev can be shared, too. ARG can also be a volume in‐
163 stead of a host folder.
164 X server options
168 --auto Automatically choose X server (default). Influenced notably by
169 options --desktop, --gpu, --wayland, --wm.
170 -h, --hostdisplay
172 Share host display :0. Quite bad container isolation! Least
173 overhead of all X server options.
174 -a, --xpra
176 Nested X server supporting seamless and --desktop mode.
177 --xpra2
179 Like --xpra --xc, but runs xpra client on host.
180 -A, --xpra-xwayland
182 Like --xpra, but supports option --gpu.
183 --xpra2-xwayland
185 Like --xpra2, but supports option --gpu.
186 -n, --nxagent
188 Nested X server supporting seamless and --desktop mode. Faster
189 than --xpra, but can have compositing issues.
190 -y, --xephyr
192 Nested X server for --desktop mode. Without --desktop a host
193 window manager will be provided (option --wm).
194 -Y, --weston-xwayland
196 Desktop mode like --xephyr, but supports option --gpu. Runs
197 from console, within X and within Wayland.
198 -x, --xorg
200 Core Xorg server. Runs ootb from console. Switch tty with
201 <CTRL><ALT><F1>....<F12>. Always switch to a black tty before
202 switching to X to avoid possible crashes.
203 Special X server options
207 -t, --tty
208 Terminal only mode. Does not run an X or Wayland server.
209 --xvfb Invisible X server using Xvfb. Can be used for custom access
211 with xpra or VNC.
212 -X, --xwayland
214 Blanc Xwayland, needs a running Wayland compositor.
215 --xwin X server to run in Cygwin/X on MS Windows.
217 --runx X server wrapper for VcXsrv and Xwin on MS Windows.
219 Wayland instead of X
223 -W, --wayland
224 Automatically set up a Wayland environment. Chooses one of fol‐
225 lowing options and regards --desktop.
226 -T, --weston
228 Weston without X for pure Wayland applications. Runs in X, in
229 Wayland or from console.
230 -K, --kwin
232 KWin without X for pure Wayland applications. Runs in X, in
233 Wayland or from console.
234 -H, --hostwayland
236 Share host Wayland without X for pure Wayland apps.
237 X and Wayland appearance options
241 --border [=COLOR] Draw a colored border in windows of xpra.
242 Argument COLOR can be e.g. orange or #F00. Thickness can be
243 specified, too, e.g. red,3. Default: blue,1
244 --dpi=N
246 dpi value (N dots per inch) to submit to X clients. Influences
247 font size of some applications.
248 -f, --fullscreen
250 Run in fullscreen mode.
251 --output-count=N
253 Multiple virtual monitors for Weston or KWin.
254 --rotate=N
256 Rotate display (--xorg, --weston and --weston-xwayland) Allowed
257 values: 0, 90, 180, 270, flipped, flipped-90, flipped-180,
258 flipped-270. (flipped means mirrored)
259 --scale=N
261 Scale/zoom factor N for xpra, Xorg or Weston. Allowed for
262 --xpra* and --xorg: 0.25...8.0. Allowed for --weston and --we‐
263 ston-xwayland: 1...9.
264 --size=WxH
266 Screen size of new X server (e.g. 800x600).
267 -w, --wm [=ARG]
269 Provide a host window manager to container applications. (In
270 case of --xc only openbox is provided.) Possible ARG:
271 host autodetection of a host window manager.
272 COMMAND command for a desired host window manager.
273 none Run without a window manager. Same as --desktop.
274 -F, --xfishtank
276 Show fish tank on new X server.
277 X and Wayland special configuration
281 --checkwindow [=ARG]
282 Run container until all X windows are closed. If ARG is pro‐
283 vided, run container as long as grep can find ARG in output of
284 xwininfo -root -children. This option helps to keep alive con‐
285 tainers with self-forking applications like gnome-terminal or to
286 stop endless running ones like chromium.
287 --clean-xhost
289 Disable xhost access policies on host display.
290 --composite [=yes|no]
292 Enable or disable X extension Composite. Default is yes except
293 for --nxagent. Can cause or fix issues with some applications on
294 nxagent.
295 --display=N
297 Run new X server with display number N. Must not be already in
298 use.
299 --keymap=LAYOUT
301 Set keyboard layout for new X server, e.g. de, us, ru. For pos‐
302 sible LAYOUT look at /usr/share/X11/xkb/symbols.
303 --vt [=N]
305 Use vt / tty N. Without optional N search an unused tty.
306 --westonini=FILE
308 Custom weston.ini for --weston and --weston-xwayland.
309 --xhost [=STR]
311 Set xhost STR on new X server (see man xhost). Without optional
312 STR will set: +SI:localuser:$USER . (Use with care. --xhost=+
313 allows access for everyone).
314 --xoverip [=yes|no|listentcp|socat] Connect to X over TCP network. Spe‐
316 cial
317 setups only, usually only enabled by x11docker itself.
318 yes Use listentcp if possible, otherwise socat.
319 no Use shared unix socket (general default).
320 listentcp Use X option -listen tcp.
321 socat Use socat to create a fake TCP connection.
322 --xauth [=yes|trusted|untrusted|no] Configure X cookie authentication.
324 Possible arguments:
325 yes|trusted Enable cookie authentication with trusted cookies.
326 (General x11docker default.)
327 untrusted Untrusted cookie for untrusted apps limiting access
328 to X resources. Useful to avoid MIT-SHM with --hostdisplay.
329 no Disable cookie authentication. Dangerous!
330 --xtest [=yes|no] Enable or disable X extension XTEST. Default is yes
332 for
333 --xpra and --xvfb, no for other X servers. Needed to allow key‐
334 board and mouse control with xpra.
335 Container user settings
339 --group-add=GROUP
340 Add container user to group GROUP.
341 --hostuser=USER
343 Run X (and container user) as user USER. Default is result of
344 $(logname). (x11docker must run as root).
345 --password [=WORD]
347 Change container user password and exit. Interactive input if
348 argument WORD is not provided. Stored encrypted in ~/.con‐
349 fig/x11docker/passwd.
350 --sudouser [=nopasswd]
352 Allow su and sudo for container user. Use with care, severe re‐
353 duction of default x11docker security! Optionally passwordless
354 sudo with argument nopasswd. Default password is x11docker.
355 --user=U
357 Create container user U (U=name or U=uid). Default: same as host
358 user. U can also be an unknown user id. You can specify a group
359 id with U being user:gid. Special case: --user=RETAIN keeps im‐
360 age user settings.
361 Container capabilities
365 In most setups x11docker sets --cap-drop=ALL --secu‐
366 rity-opt=no-new-privileges and shows warnings if doing other‐
367 wise. Custom capabilities can be added with --cap-add=CAP after
368 --
369 --cap-default
371 Allow default container capabilities. Includes --newprivi‐
372 leges=yes.
373 --ipc [=ARG]
375 Without optional ARG sets run option --ipc=host (discouraged).
376 For other possible ARG see docker run reference.
377 --limit [=FACTOR]
379 Limit CPU and RAM usage of container to currently free RAM x
380 FACTOR and available CPUs x FACTOR. Allowed range is 0 < FACTOR
381 <= 1. Default for --limit without optional argument FACTOR is
382 0.5 .
383 --newprivileges [=yes|no|auto]
385 Set or unset run option --security-opt=no-new-privileges. De‐
386 fault with no argument is yes. Default for most cases is no.
387 Container init system, elogind and DBus daemon
391 --dbus [=system]
392 Run DBus user session daemon for container command. With argu‐
393 ment system also run a DBus system daemon. (To run a DBus sys‐
394 tem daemon rather use one of --init=sys‐
395 temd|openrc|runit|sysvinit )
396 --hostdbus
398 Connect to DBus user session from host.
399 --init [=tini|systemd|openrc|runit|sysvinit|s6-overlay|none]
401 Run an init system as PID 1 in container. Solves the zombie
402 reaping issue. By default x11docker uses tini or the similar
403 catatonit.
404 --sharecgroup
406 Share /sys/fs/cgroup. Allows elogind in container if used with
407 one of --init=openrc|runit|sysvinit
408 Container special configuration:
412 --env VAR=value
413 Set custom environment variable.
414 --name=NAME
416 Specify container name NAME.
417 --no-entrypoint
419 Disable ENTRYPOINT in image to allow other commands, too
420 --no-setup
422 No x11docker setup in running container. Disallows several other
423 options. See also --user=RETAIN.
424 --runtime=RUNTIME
426 Specify container runtime. Known by x11docker:
427 runc Default runtime of docker.
428 crun Default runtime of podman.
429 nvidia Runtime for nvidia/nvidia-docker images.
430 sysbox-runc Runtime for powerful root in container.
431 --shell=SHELL
433 Set preferred user shell. Example: --shell=/bin/zsh
434 --snap Enable support for Docker in snap.
436 --stdin
438 Forward stdin of x11docker to container command.
439 --workdir=DIR
441 Set working directory DIR.
442 Additional commands
446 You might need to move them to background with CMD &.
447 --runasroot=CMD
449 Run command CMD as root in container.
450 --runasuser=CMD
452 Run command CMD with user privileges in container before running
453 image command.
454 --runfromhost=CMD Run host command CMD on new X server.
456 Miscellaneous
460 --build IMAGE
461 Build an image from a Dockerfile from x11docker repository. Ex‐
462 ample: x11docker --build x11docker/fvwm . Works for all reposi‐
463 tories beginning with 'dockerfile' at
464 https://github.com/mviereck?tab=repositories . Regards (only)
465 option --backend=BACKEND.
466 --cachebasedir=DIR
468 Custom base folder for cache files.
469 --homebasedir=DIR
471 Custom base folder for option --home.
472 --fallback [=yes|no]
474 Allow or deny fallbacks if a chosen option cannot be fulfilled.
475 By default fallbacks are allowed.
476 --launcher
478 Create application launcher with current options on desktop and
479 exit. You can get a menu entry moving the created *.desktop file
480 to ~/.local/share/applications
481 --mobyvm
483 Use MobyVM (for WSL2 only that defaults to Linux Docker).
484 --preset=FILE
486 Read a set of predefined options stored in file FILE. Useful to
487 shortcut often used option combinations.
488 FILE is searched in directory /etc/x11docker/preset, or in di‐
489 rectory ~/.config/x11docker/preset.
490 Multiple lines in FILE are allowed.
491 Comment lines must begin with # .
492 Local presets supersede global ones in /etc .
493 Special case: A preset file with file name default will be ap‐
494 plied automatically for all x11docker sessions.
495 Output of parseable information on stdout
499 Get output e.g. with: read xenv < <(x11docker --printenv
500 x11docker/check) . Optional argument FILE allows to print the
501 information into a file.
502 --printenv [=FILE]
504 Print variables to access new display.
505 --printid [=FILE]
507 Print container ID.
508 --printinfofile [=FILE]
510 Print path to internal x11docker info storage.
511 --printpid1 [=FILE]
513 Print host PID of container PID 1.
514 Verbosity options
518 -D, --debug
519 Enable rigorous error control and show some debug output.
520 --printcheck
522 Show dependency check messages.
523 -q, --quiet
525 Suppress x11docker terminal messages.
526 -v, --verbose
528 Be verbose. Output of x11docker.log on stderr.
529 -V Be verbose with colored output.
531 Cleanup options (might need root permissions)
535 --cleanup
536 Clean up orphaned containers and cache files. Those can remain
537 if x11docker still runs on system shutdown. Terminates cur‐
538 rently running x11docker containers, too. Regards (only) option
539 --backend=BACKEND.
540 Installation options (need root permissions)
544 These options might not be available in packaged versions of x11docker.
545 --install
547 Install x11docker from current folder. Useful to install from
548 an extracted zip file.
549 --update [=diff]
551 Download and install latest release from github.
552 --update-master [=diff]
554 Download and install latest master version. Optional argument
555 diff shows the difference between installed and new version
556 without installing it.
557 --remove
559 Remove x11docker from your system. Includes --cleanup. Pre‐
560 serves ~/.local/share/x11docker from option --home.
561 --remove-oldprefix
563 Before version 7.6.0 x11docker installed itself into /usr/bin.
564 Now it installs into /usr/local/bin. Use --remove-oldprefix to
565 remove /usr/bin installations.
566
570 Package names and further optional dependencies:
571 https://github.com/mviereck/x11docker/wiki/Dependencies
572 Dependencies on host:
575 For core functionality x11docker only needs bash, an X server
576 and one of docker, podman or nerdctl. Depending on chosen op‐
577 tions x11docker might need some additional tools. It checks for
578 them on startup and shows messages if some are missing.
579 * Most recommended: Provide image x11docker/xserver to run X or
581 Wayland in container. The image contains all X related dependen‐
582 cies.
583 Otherwise provide on host:
585 * Recommended to allow security and convenience:
587 X servers: some of: nxagent xpra Xephyr Xorg
588 Tools: all of: xauth xclip xrandr xhost xinit catatonit
589 * Additionally for advanced GPU support: weston Xwayland xpra
591 xdotool
592 Dependencies in image:
595 No dependencies in image except for a few feature options. Most
596 important:
597 --gpu: OpenGL/MESA packages, collected often in mesa-utils package.
599 For closed source NVIDIA support look at
600 https://github.com/mviereck/x11docker/wiki/NVIDIA-driver-sup‐
601 port-for-docker-container
602 --pulseaudio: Needs pulseaudio on host and pulseaudio client libs in
604 image.
605 --printer: Needs cups on host and cups client libs in image.
607
611 0 Success
612 64 x11docker error
614 130 Terminated by ctrl-c
616 other Exit code of command in container
618
622 FVWM window manager:
623 x11docker --desktop x11docker/fvwm
624 Xfce desktop:
625 x11docker --desktop x11docker/xfce
626 Accelerated glxspheres:
627 x11docker --gpu x11docker/check glxspheres64
628 Kodi media center with hardware acceleration, pulseaudio sound, shared
629 Videos folder and persistant HOME:
630 x11docker --gpu --pulseaudio --home --share=~/Videos erichough/kodi
631 Firefox with shared Downloads folder and internet access:
632 x11docker -I --share $HOME/Downloads -- --tmpfs /dev/shm --
633 jess/firefox
634
637 Written by Martin Viereck, Germany.
638
642 Please report issues and get help at:
643 https://github.com/mviereck/x11docker/issues
644
648 x11docker is published under the MIT licence. Check the output of
649 x11docker --licence . This is free software: you are free to change
650 and redistribute it. There is NO WARRANTY, to the extent permitted by
651 law.
652
656 Further documentation at:
657 https://github.com/mviereck/x11docker
658 https://github.com/mviereck/x11docker/wiki
659 X11DOCKER(1)