Add Linux X11 forwarding feature

.devcontainer/gz-smoke/devcontainer.json

@@ -0,0 +1,29 @@
+{
+  "name": "gz-smoke",
+  "image": "althack/gz:jetty-base",
+  "remoteUser": "ros",
+  "updateRemoteUserUID": true,
+  "containerEnv": {
+    "GZ_VERSION": "jetty"
+  },
+  "runArgs": [
+    "--network=host",
+    "--ipc=host",
+    "--cap-add=SYS_PTRACE",
+    "--security-opt=seccomp:unconfined",
+    "--security-opt=apparmor:unconfined"
+  ],
+  "features": {
+    "../local-features/linux-x11-forwarding": {}
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-vscode.cpptools",
+        "ms-python.python",
+        "twxs.cmake",
+        "redhat.vscode-yaml"
+      ]
+    }
+  }
+}

.devcontainer/linux-x11-forwarding-smoke/devcontainer.json

@@ -0,0 +1,10 @@
+{
+  "name": "linux-x11-forwarding-smoke",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+  "features": {
+    "../local-features/linux-x11-forwarding": {
+      "x11Display": "${localEnv:DISPLAY}"
+    }
+  },
+  "postCreateCommand": "sudo apt-get update && sudo apt-get install -y x11-apps"
+}

.devcontainer/local-features/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

.devcontainer/prepare-local-features.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+local_features_dir="${repo_root}/.devcontainer/local-features"
+
+mkdir -p "${local_features_dir}"
+rm -rf "${local_features_dir}/linux-x11-forwarding" "${local_features_dir}/x11" "${local_features_dir}/wayland"
+cp -R "${repo_root}/features/src/linux-x11-forwarding" "${local_features_dir}/linux-x11-forwarding"
+
+echo "Prepared local smoke-test features in ${local_features_dir}"

.github/workflows/test-pr.yaml

@@ -23,6 +23,9 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Install devcontainer CLI
+        run: npm install -g @devcontainers/cli
+
       - name: Validate feature metadata
         run: bash features/test/test_all.sh
 

README.md

@@ -6,10 +6,22 @@ Devcontainer templates repository focused on robotics and simulation.
 
 - `templates/src/gz`
 
-## Included features
+## Included feature
 
-- `features/src/x11`
-- `features/src/wayland`
+- `features/src/linux-x11-forwarding` (local Linux hosts only)
+
+## Sample configs
+
+- `.devcontainer/gz-smoke/devcontainer.json`
+- `.devcontainer/linux-x11-forwarding-smoke/devcontainer.json`
+
+Before using the samples locally, run
+`bash .devcontainer/prepare-local-features.sh` so `devcontainer up` can resolve
+the unpublished Feature.
+
+On classic Xorg hosts where the authority cookie lives outside
+`XDG_RUNTIME_DIR`, add a bind mount to `/tmp/devcontainer-xauthority-host`.
+XWayland setups are auto-detected from the mounted runtime directory.
 
 ## Workflows
 

features/src/linux-x11-forwarding/NOTES.md

@@ -0,0 +1,31 @@
+## Linux host requirements
+
+This Feature supports containers running locally on a Linux desktop with Xorg or
+Wayland/XWayland. It does not configure a host X server and does not support
+Docker Desktop on macOS or Windows, remote Docker daemons, or Codespaces.
+
+The container is granted access to the host X server. Only use it with
+development containers you trust.
+
+## Xauthority
+
+For modern Wayland/XWayland desktops, the feature auto-discovers the mounted `.mutter-Xwaylandauth.*` file from `XDG_RUNTIME_DIR`.
+
+For classic Xorg setups where the authority file lives outside `XDG_RUNTIME_DIR` (often `~/.Xauthority`), add an explicit mount in the consuming `devcontainer.json`:
+
+```json
+"mounts": [
+  "source=${localEnv:XAUTHORITY},target=/tmp/devcontainer-xauthority-host,type=bind,readonly"
+]
+```
+
+The feature always exposes the stable in-container path `/tmp/devcontainer-xauthority` through `XAUTHORITY`.
+
+Qt applications are forced onto the X11 backend with `QT_QPA_PLATFORM=xcb` so they do not try to boot the Wayland plugin in X11-only containers.
+
+If the container does not already define `XDG_RUNTIME_DIR`, the Feature creates
+a private per-user directory at `/tmp/devcontainer-runtime-<uid>`. The mounted
+host runtime directory remains separate and is used only for host sockets and
+XWayland authentication.
+
+Use the `x11Display` option to set the in-container `DISPLAY` value.

features/src/linux-x11-forwarding/README.md

@@ -0,0 +1,56 @@
+
+# Linux X11 Forwarding (linux-x11-forwarding)
+
+Forward a local Linux host's X11 display into a development container.
+
+## Example Usage
+
+```json
+"features": {
+    "ghcr.io/althack/devcontainers/linux-x11-forwarding:0": {}
+}
+```
+
+## Options
+
+| Options Id | Description | Type | Default Value |
+|-----|-----|-----|-----|
+| x11Display | Set DISPLAY for X11 clients launched from the container. | string | :0 |
+| softwareGL | Set LIBGL_ALWAYS_SOFTWARE for GPU compatibility. | string | 1 |
+
+## Linux host requirements
+
+This Feature supports containers running locally on a Linux desktop with Xorg or
+Wayland/XWayland. It does not configure a host X server and does not support
+Docker Desktop on macOS or Windows, remote Docker daemons, or Codespaces.
+
+The container is granted access to the host X server. Only use it with
+development containers you trust.
+
+## Xauthority
+
+For modern Wayland/XWayland desktops, the feature auto-discovers the mounted `.mutter-Xwaylandauth.*` file from `XDG_RUNTIME_DIR`.
+
+For classic Xorg setups where the authority file lives outside `XDG_RUNTIME_DIR` (often `~/.Xauthority`), add an explicit mount in the consuming `devcontainer.json`:
+
+```json
+"mounts": [
+  "source=${localEnv:XAUTHORITY},target=/tmp/devcontainer-xauthority-host,type=bind,readonly"
+]
+```
+
+The feature always exposes the stable in-container path `/tmp/devcontainer-xauthority` through `XAUTHORITY`.
+
+Qt applications are forced onto the X11 backend with `QT_QPA_PLATFORM=xcb` so they do not try to boot the Wayland plugin in X11-only containers.
+
+If the container does not already define `XDG_RUNTIME_DIR`, the Feature creates
+a private per-user directory at `/tmp/devcontainer-runtime-<uid>`. The mounted
+host runtime directory remains separate and is used only for host sockets and
+XWayland authentication.
+
+Use the `x11Display` option to set the in-container `DISPLAY` value.
+
+
+---
+
+_Note: This file was auto-generated from the [devcontainer-feature.json](https://github.com/althack/devcontainers/blob/main/features/src/linux-x11-forwarding/devcontainer-feature.json).  Add additional notes to a `NOTES.md`._

features/src/linux-x11-forwarding/devcontainer-feature.json

@@ -0,0 +1,35 @@
+{
+  "id": "linux-x11-forwarding",
+  "version": "0.1.0",
+  "name": "Linux X11 Forwarding",
+  "description": "Forward a local Linux host's X11 display into a development container.",
+  "documentationURL": "https://github.com/althack/devcontainers/tree/main/features/src/linux-x11-forwarding",
+  "licenseURL": "https://github.com/althack/devcontainers/blob/main/LICENSE",
+  "options": {
+    "x11Display": {
+      "type": "string",
+      "default": ":0",
+      "description": "Set DISPLAY for X11 clients launched from the container."
+    },
+    "softwareGL": {
+      "type": "string",
+      "default": "1",
+      "proposals": [
+        "0",
+        "1"
+      ],
+      "description": "Set LIBGL_ALWAYS_SOFTWARE for GPU compatibility."
+    }
+  },
+  "containerEnv": {
+    "XAUTHORITY": "/tmp/devcontainer-xauthority",
+    "PULSE_SERVER": "unix:/tmp/devcontainer-host-runtime/pulse-native"
+  },
+  "mounts": [
+    "source=/tmp/.X11-unix,target=/tmp/.X11-unix,type=bind",
+    "source=${localEnv:XDG_RUNTIME_DIR},target=/tmp/devcontainer-host-runtime,type=bind"
+  ],
+  "installsAfter": [
+    "ghcr.io/devcontainers/features/common-utils"
+  ]
+}

features/src/linux-x11-forwarding/install.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+x11_display="${X11DISPLAY:-:0}"
+software_gl="${SOFTWAREGL:-1}"
+
+cat >/etc/profile.d/devcontainer-x11-gui.sh <<EOF
+host_runtime_dir="/tmp/devcontainer-host-runtime"
+mounted_xauthority="/tmp/devcontainer-xauthority-host"
+xauthority_target="/tmp/devcontainer-xauthority"
+
+if [ -z "\${XDG_RUNTIME_DIR:-}" ]; then
+    container_runtime_dir="/tmp/devcontainer-runtime-\$(id -u)"
+    mkdir -p "\${container_runtime_dir}"
+    chmod 0700 "\${container_runtime_dir}"
+    export XDG_RUNTIME_DIR="\${container_runtime_dir}"
+fi
+
+if [ -e "\${mounted_xauthority}" ]; then
+    ln -snf "\${mounted_xauthority}" "\${xauthority_target}"
+else
+    set -- "\${host_runtime_dir}"/.mutter-Xwaylandauth.*
+    if [ -e "\$1" ]; then
+        ln -snf "\$1" "\${xauthority_target}"
+    else
+        rm -f "\${xauthority_target}"
+    fi
+fi
+
+export DISPLAY="${x11_display}"
+export LIBGL_ALWAYS_SOFTWARE="${software_gl}"
+export QT_QPA_PLATFORM="xcb"
+export XAUTHORITY="\${xauthority_target}"
+EOF
+
+chmod 0644 /etc/profile.d/devcontainer-x11-gui.sh
+
+echo "X11 feature metadata configured."