From 5ae60c76f215c9d2c7a1b4a9681b4f38d41941e4 Mon Sep 17 00:00:00 2001
From: Eden Reich <eden.reich@gmail.com>
Date: Sat, 18 Oct 2025 20:48:34 +0200
Subject: [PATCH] docs(a2a): Add VNC support for browser-agent with Docker
 configuration

Signed-off-by: Eden Reich <eden.reich@gmail.com>
---
 examples/a2a/Dockerfile.vnc      | 29 +++++++++++++++++++++++++++++
 examples/a2a/README.md           | 30 ++++++++++++++++++++++++++++++
 examples/a2a/docker-compose.yaml | 19 +++++++++++++++++++
 3 files changed, 78 insertions(+)
 create mode 100644 examples/a2a/Dockerfile.vnc

diff --git a/examples/a2a/Dockerfile.vnc b/examples/a2a/Dockerfile.vnc
new file mode 100644
index 00000000..e53b7899
--- /dev/null
+++ b/examples/a2a/Dockerfile.vnc
@@ -0,0 +1,29 @@
+FROM alpine:latest
+
+# Install x11vnc
+RUN apk add --no-cache x11vnc
+
+# Create a startup script that connects to the shared X display
+COPY <<'EOF' /usr/local/bin/start-vnc.sh
+#!/bin/sh
+set -e
+
+echo "Waiting for X display :99 to be available..."
+echo "Checking /tmp/.X11-unix directory..."
+ls -la /tmp/.X11-unix/ 2>/dev/null || echo "Directory not found or empty"
+
+while true; do
+  if [ -S /tmp/.X11-unix/X99 ]; then
+    echo "X11 socket found, attempting to start x11vnc..."
+    x11vnc -display :99 -forever -shared -passwd password -rfbport 5900 -listen 0.0.0.0 -noshm && break
+  else
+    echo "Waiting for /tmp/.X11-unix/X99 socket... ($(date))"
+    ls -la /tmp/.X11-unix/ 2>/dev/null || echo "Directory still empty"
+  fi
+  sleep 5
+done
+EOF
+
+RUN chmod +x /usr/local/bin/start-vnc.sh
+
+ENTRYPOINT ["/usr/local/bin/start-vnc.sh"]
diff --git a/examples/a2a/README.md b/examples/a2a/README.md
index 6042cc9e..63d7bb19 100644
--- a/examples/a2a/README.md
+++ b/examples/a2a/README.md
@@ -45,6 +45,36 @@ Now you can enter the Interactive Chat within the cli container and start chatti
 docker compose run --rm cli
 ```
 
+## Viewing Browser Agent GUI
+
+The browser-agent can run in headed mode with VNC support for real-time viewing of browser automation.
+
+**Requirements:**
+
+1. Browser-agent v0.4.0+ with Xvfb support
+2. `BROWSER_HEADLESS: false` environment variable set
+3. Shared X11 socket volume between browser-agent and browser-vnc
+
+**Usage:**
+
+Connect to the VNC server on port 5900:
+
+```bash
+# Using a VNC client (e.g., RealVNC, TigerVNC, or macOS Screen Sharing)
+# Connect to: localhost:5900
+# Password: password
+```
+
+On macOS, you can use the built-in Screen Sharing app:
+
+```bash
+open vnc://localhost:5900
+# When prompted, enter password: password
+```
+
+**Note:** The X11 display is created by Xvfb when the browser-agent container starts. The VNC server will connect
+automatically and you can view browser automation in real-time.
+
 ## Troubleshooting
 
 ```bash
diff --git a/examples/a2a/docker-compose.yaml b/examples/a2a/docker-compose.yaml
index d2eee8f7..fec1ea94 100644
--- a/examples/a2a/docker-compose.yaml
+++ b/examples/a2a/docker-compose.yaml
@@ -137,6 +137,7 @@ services:
     environment:
       ENVIRONMENT: development
       BROWSER_DATA_DIR: /tmp/playwright
+      BROWSER_HEADLESS: false
       A2A_AGENT_URL: http://browser-agent:8080
       A2A_AGENT_CLIENT_PROVIDER: deepseek
       A2A_AGENT_CLIENT_MODEL: deepseek-chat
@@ -159,6 +160,23 @@ services:
       A2A_ARTIFACTS_RETENTION_CLEANUP_INTERVAL: 24h
     volumes:
       - ./agents/browser-agent:/tmp/artifacts
+      - x11-socket:/tmp/.X11-unix
+    restart: unless-stopped
+    networks:
+      - a2a-network
+
+  browser-vnc:
+    build:
+      context: .
+      dockerfile: Dockerfile.vnc
+    environment:
+      DISPLAY: :99
+    volumes:
+      - x11-socket:/tmp/.X11-unix
+    ports:
+      - "5900:5900"
+    depends_on:
+      - browser-agent
     restart: unless-stopped
     networks:
       - a2a-network
@@ -189,3 +207,4 @@ networks:
 volumes:
   go-modules:
   go-build-cache:
+  x11-socket: