vnc-service:run

VNC Service Run

Ensure the virtual display and VNC server are running, and provide connection details. This is the skill other plugins call when they need browser interaction on a headless server.

Workflow

Step 1: Check if Setup Has Been Done

test -f ~/.config/systemd/user/virtual-display.service && echo "SETUP" || echo "NOT_SETUP"

If not set up: inform the user and invoke /vnc-service:setup. Do not proceed until setup completes.

Step 2: Ensure Services Are Running

Start the display first, wait for it, then start VNC:

# Start display if not running
if ! systemctl --user is-active virtual-display.service >/dev/null 2>&1; then
  systemctl --user start virtual-display.service
fi

# Wait for display :99 to be ready (up to 15 seconds)
for i in $(seq 1 30); do
  DISPLAY=:99 xdpyinfo >/dev/null 2>&1 && break
  sleep 0.5
done

# Start VNC if not running
if ! systemctl --user is-active vnc-server.service >/dev/null 2>&1; then
  systemctl --user start vnc-server.service
fi

Step 3: Verify Display

DISPLAY=:99 xdpyinfo >/dev/null 2>&1 && echo "OK" || echo "FAIL"

If display check fails:

1. Check if Xvfb process exists: pgrep -f "Xvfb :99" | head -1
2. Check for stale lock: inspect PID in /tmp/.X99-lock, remove if dead, then restart service
3. Check service logs: journalctl --user -u virtual-display.service --no-pager -n 20

Step 4: Verify VNC

ss -tlnp | grep -q 5999 && echo "OK" || echo "FAIL"

If VNC check fails, restart the vnc-server service.

Step 5: Report Connection Info

Determine the server's IP address:

SERVER_IP=$(hostname -I | awk '{print $1}')

Print:

VNC Ready (localhost only — SSH tunnel required)
  1. From your PC: ssh -L 5999:localhost:5999 <user>@<server-ip>
  2. Connect VNC client to: localhost:5999
  Display: :99 (set DISPLAY=:99 for browser commands)

Step 6: Wait for User

If called as a prerequisite for another operation (e.g., CAPTCHA solve or OAuth):

• Print the connection info
• Ask: "Connect to VNC now (SSH tunnel + VNC client). Let me know when you're connected."
• Wait for user confirmation before returning

Usage by Other Skills

Other skills should call /vnc-service:setup as a prerequisite check and /vnc-service:run before browser operations:

### Prerequisite: Virtual Display

If the environment is headless (no DISPLAY set):
1. Invoke /vnc-service:setup to ensure VNC is installed
2. Invoke /vnc-service:run to ensure running and get connection info
3. Wait for user to confirm VNC connection
4. Set DISPLAY=:99 before running browser commands