diff --git a/Makefile b/Makefile
index 6e299005..c579bbf5 100644
--- a/Makefile
+++ b/Makefile
@@ -463,6 +463,7 @@ images_deps_xterm: image_docker_compose images_deps
 
 images: images_deps image_runner_node image_dnsmasq image_gpg_pk image_dev_shell image_acng image_auth_proxy image_container_proxy image_lsp_node
 
+images_gui: images image_xterm image_firefox image_vnc
 
 images_test: images image_nvim_test
 
diff --git a/docs/graphical-applications.md b/docs/graphical-applications.md
new file mode 100644
index 00000000..43b658ca
--- /dev/null
+++ b/docs/graphical-applications.md
@@ -0,0 +1,84 @@
+# Running graphical applications
+
+For launching graphical applications like terminal, web browser, and graphical IDE, there are two options, in either case utilizing X11:
+
+1. A self-hosted X server running a dedicated desktop environment accessible over VNC
+  - Recommended
+2. Using a provided X socket
+  - Affords more seamless integration at the cost of reduced isolation. Only recommended for advanced users.
+
+## Requirements
+
+The GUI-based images need to be built separately:
+
+```
+$ make images_gui
+```
+
+You will also want a VNC client. TigerVNC `vncviewer` is recommended.
+
+## 1. Using a self-hosted X server
+
+## Starting the desktop environment
+
+By default, graphical applications will launch in a dedicated X server accessible via VNC. Currently, the display server needs to be started explicitly:
+
+```
+$ podman compose up --no-deps --build --force-recreate vnc
+
+# output generated vnc passwords
+$ podman compose exec vnc cat /home/user/.local/vnc/admin_vncpasswd
+$ podman compose exec vnc cat /home/user/.local/vnc/view_vncpasswd
+
+# open remote control
+$ vncviewer 127.0.0.1:5902
+```
+
+### Launching applications
+#### From the dev-shell
+
+Provided applications will be launched directly in the VNC server if started from the shell. For example:
+
+```
+$ de
+> firefox
+```
+
+### Inside the desktop environment
+
+The default window manager is [ratpoison](https://www.nongnu.org/ratpoison/).
+
+Refer to `imags/X11/vnc/skel/.ratpoisonrc` for customization and complete reference.
+
+### Basic key bindings
+
+- `Ctrl+Esc ?`: Display keybindings
+- `Ctrl+Esc c`: New terminal window
+- `Ctrl+Esc d`: Application launcher
+- `Ctrl+Esc w`: New firefox window
+- `Ctrl+Esc n`: Next window
+- `Ctrl+Esc Tab`: Focus next
+- `Ctrl+Esc s`: Split horizontally
+- `Ctrl+Esc S`: Split vertically
+- `Ctrl+Esc L`: Reload `~/.ratpoisonrc`
+
+## 2. Using a provided X socket
+
+If you have an existing X server you would like to use, you can mount and forward an existing socket.
+When launching the environment or application, you will need to specify environment variables:
+- `L7_X11_SOCKET_VOLUME`: The directory where the socket resides
+- `L7_XAUTHORITY`: The path to the Xauthority file
+- `L7_DISPLAY`: The DISPLAY number or path
+
+For example, to launch firefox in the current X session in a typical Linux environment:
+
+```
+$ export L7_X11_SOCKET_VOLUME=/tmp/.X11-unix L7_DISPLAY=${DISPLAY:-:0} L7_XAUTHORITY="${HOME}/.Xauthority"
+$ de
+> firefox
+```
+
+You can also provide the options directly in an existing shell session:
+```
+> L7_X11_SOCKET_VOLUME=/tmp/.X11-unix L7_DISPLAY=:0 L7_XAUTHORITY=/home/xyz/.Xauthority firefox
+```
diff --git a/docs/vnc.md b/docs/vnc.md
deleted file mode 100644
index 6adc54cf..00000000
--- a/docs/vnc.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Remote collaboration with VNC
-
-There is an experimental VNC image which provides a graphical X11 environment with terminal, web browser, and remote-viewing capabilities:
-
-To run and connect a viewer locally:
-```
-$ make -j4 images
-$ make image_vnc
-$ podman compose up --no-deps --build --force-recreate vnc
-
-# output generated vnc passwords
-$ podman compose exec vnc cat /home/user/.local/vnc/admin_vncpasswd
-$ podman compose exec vnc cat /home/user/.local/vnc/view_vncpasswd
-
-# open remote control
-$ vncviewer 127.0.0.1:5902
-```
-
-### Basic hotkeys
-
-- `Ctrl+Esc c`: New terminal window
-- `Ctrl+Esc w`: New firefox window
-- `Ctrl+Esc d`: Application launcher
-- `Ctrl+Esc ?`: Display keybindings
-- `Ctrl+Esc L`: Reload `~/.ratpoisonrc`
-
-Refer to `imags/X11/vnc/skel/.ratpoisonrc` for customization and complete reference.