second-brain/XVFB-ON-DEMAND.md

Xvfb + x11vnc On-Demand Setup

Run X11 server only when needed — zero overhead when idle.

How It Works

No one using X11
    ↓
Xvfb is STOPPED (no resources)

VNC client connects (or app needs X11)
    ↓
Systemd socket activation
    ↓
Xvfb starts automatically
    ↓
x11vnc connects to it
    ↓
You can use X11 apps or remote desktop

When done / no activity for N minutes
    ↓
Xvfb stops (auto)

Installation

1. Install Packages

sudo apt-get update
sudo apt-get install -y x11vnc xvfb

2. Install Systemd Services

sudo cp /workspace/second-brain/xvfb.socket /etc/systemd/system/
sudo cp /workspace/second-brain/xvfb.service /etc/systemd/system/
sudo cp /workspace/second-brain/x11vnc.service /etc/systemd/system/

sudo systemctl daemon-reload

3. Enable Socket Activation (for Xvfb)

sudo systemctl enable xvfb.socket
sudo systemctl start xvfb.socket

4. Enable VNC Service

sudo systemctl enable x11vnc.service
# Don't start yet — it will start when xvfb.socket gets activity

5. Verify Setup

# Socket should be listening
sudo systemctl status xvfb.socket

# Services should be inactive initially
sudo systemctl status xvfb.service
sudo systemctl status x11vnc.service

Usage

Start On-Demand

Option A: VNC Connection Triggers It

# From another machine, connect to VNC
vnc-viewer 192.168.x.x:5900
# → x11vnc and Xvfb start automatically

Option B: Manual Start

# If you want to start without VNC connection
sudo systemctl start xvfb.service
sudo systemctl start x11vnc.service

Option C: Any App Needing X11

# Any X11 app trying to connect to :99 will trigger it
DISPLAY=:99 firefox &
# → Xvfb starts automatically

Monitoring

Watch Activation

# See when services start/stop
sudo journalctl -fu xvfb
sudo journalctl -fu x11vnc

Check Current Status

# Is Xvfb running?
ps aux | grep Xvfb

# Is VNC listening?
netstat -tlnp | grep 5900

Configuration

Change VNC Port

Edit /etc/systemd/system/x11vnc.service:

ExecStart=/usr/bin/x11vnc -display :99 -forever -nopw -rfbport 5901

Then reload:

sudo systemctl daemon-reload
sudo systemctl restart x11vnc.service

Allow Remote Connections

Edit /etc/systemd/system/x11vnc.service:

# Change -localhost to -listen 0.0.0.0
ExecStart=/usr/bin/x11vnc -display :99 -forever -nopw -listen 0.0.0.0

Add VNC Password

# Generate password
x11vnc -storepasswd

# Update service to use it
ExecStart=/usr/bin/x11vnc -display :99 -forever -listen localhost -usepw

Adjust Display Resolution

Edit /etc/systemd/system/xvfb.service:

# Change 1920x1080x24 to your desired resolution
ExecStart=/usr/bin/Xvfb :99 -screen 0 2560x1440x24

Auto-Stop (Inactivity)

To stop Xvfb after no activity (optional):

# Install x-idle-logout if available
# Or use a watchdog script

cat > /usr/local/bin/xvfb-watchdog.sh << 'EOF'
#!/bin/bash
# Stop Xvfb after 30 minutes of inactivity
while true; do
  if ! pgrep -x Xvfb > /dev/null; then
    sleep 300
    continue
  fi
  
  # Check if anyone is using the display
  xset -display :99 -q 2>/dev/null && IDLE=$(xset -display :99 q | grep "DPMS" | grep -oP '\d+m \d+s' | head -1)
  
  if [ -z "$IDLE" ]; then
    # 30 minutes of inactivity
    sudo systemctl stop xvfb.service
    echo "Stopped Xvfb due to inactivity"
    sleep 600
  fi
  
  sleep 60
done
EOF

chmod +x /usr/local/bin/xvfb-watchdog.sh

# Add to systemd (optional)
sudo systemctl enable xvfb-watchdog.service

Troubleshooting

Xvfb won't start

sudo journalctl -u xvfb.service -n 20
# Look for errors, usually permission or display binding issues

Can't connect to VNC

# Check if x11vnc is running
ps aux | grep x11vnc

# Check if port 5900 is listening
sudo lsof -i :5900

# Check logs
sudo journalctl -u x11vnc.service -n 20

Permissions error

# Make sure x11vnc can access the display
sudo chown -R intense:intense /tmp/.X11-unix/
sudo chmod 1777 /tmp/.X11-unix/

Performance

• Idle overhead: <1MB RAM (Xvfb stopped)
• Running Xvfb: ~100-200MB RAM
• With VNC client: +50-100MB
• CPU: Only when rendering, otherwise idle

---

Created: 2026-04-26