How to Set Up VNC Remote Desktop Access on Raspberry Pi with OpenClaw

Raspberry Pi shipped 7.6 million boards in FY2025, a 9% increase over the previous year. A growing share of those boards run headless: no monitor, no keyboard, tucked into a closet or mounted on a shelf. And with the Bookworm OS release, the display server changed from X11 to Wayland, which broke the RealVNC integration that had been baked into Raspberry Pi OS for years.

That shift matters when you run an OpenClaw agent on the Pi. OpenClaw turns the board into an always-on AI gateway where the Pi handles orchestration and local state while models run in the cloud through API calls. You can SSH into the Pi for terminal work, but some tasks are easier with a graphical view: checking system monitors, debugging a GUI application the agent interacts with, or verifying that the desktop environment came up cleanly after a power cycle.

VNC provides that graphical window from your laptop or phone without needing a physical display connected to the Pi. The official Raspberry Pi remote access documentation covers the built-in options, but the challenge is choosing the right VNC approach for Bookworm's Wayland compositor and making it coexist with an OpenClaw agent that is already consuming system resources.

Raspberry Pi OS Bookworm gives you three paths to remote graphical access. Each trades setup complexity against reach and features.

wayvnc (built-in, free, LAN)

wayvnc ships with Raspberry Pi OS Bookworm as the native VNC server. It speaks Wayland directly, so there is no compatibility shim or translation overhead. You enable it through raspi-config or install it with sudo apt install wayvnc. It listens on port 5900 and works with any standard VNC client like TigerVNC or RealVNC Viewer.

Strengths: zero cost, no account needed, minimal CPU overhead on the Pi. Limitation: LAN-only unless you add SSH tunneling or a VPN like Tailscale.

RealVNC Connect (cloud relay, freemium)

RealVNC used to ship preinstalled on Raspberry Pi OS, but the Wayland transition ended that default integration. RealVNC Connect is still available as a separate install. Their Lite plan is free for non-commercial, local-network use. Cloud relay access, which lets you connect from outside your LAN without port forwarding, starts at $8.25/month on the Essentials plan.

Strengths: cloud connectivity without router configuration, encrypted relay infrastructure. Limitation: the free tier is LAN-only, same effective reach as wayvnc but with more setup steps.

Raspberry Pi Connect (browser-based, free tier)

Raspberry Pi Connect is the official cloud remote access service from Raspberry Pi Ltd. It runs entirely in your browser, so you do not need a VNC client installed on your computer. Desktop sharing works on Pi 4 and Pi 5. Since March 2026, Connect also supports triggering over-the-air OS updates from the browser without opening a remote session.

Strengths: no client software required, works from any device with a browser, minimal configuration. Limitation: requires a Raspberry Pi ID account, and desktop sharing is limited to Pi 4 and newer models.

For an OpenClaw agent Pi that sits on your home or office network, wayvnc is the simplest starting point. You get graphical access with the least overhead, and you can always add Tailscale or Pi Connect later if you need access from outside your LAN.

This walkthrough assumes you have a Raspberry Pi 4 or Pi 5 running a fresh Raspberry Pi OS Bookworm (64-bit) install. If you have not installed the OS yet, use the official Raspberry Pi Imager and enable SSH during the setup wizard so you can access the Pi without a monitor from the start.

Step 1: Enable VNC through raspi-config

SSH into your Pi and run:

sudo raspi-config

Navigate to Interface Options, select VNC, and confirm Yes. This installs and enables wayvnc if it is not already present.

Alternatively, install it directly:

sudo apt update
sudo apt install wayvnc -y

Step 2: Configure the headless display

Without a physical monitor connected, the Pi may skip rendering a desktop entirely. You will connect via VNC and see a black screen. Fix this by editing /boot/firmware/config.txt and adding:

framebuffer_width=1280
framebuffer_height=720

Use 1280x720 rather than 1080p to keep bandwidth and CPU usage low on a board that is also running an agent. Reboot after making this change.

Step 3: Create a systemd service for auto-start

You want wayvnc to launch automatically when the desktop session loads. Create a user-level systemd unit at ~/.config/systemd/user/wayvnc.service:

[Unit]
Description=wayvnc VNC Server
After=graphical-session.target

[Service]
ExecStart=/usr/bin/wayvnc 0.0.0.0 5900
Restart=on-failure

[Install]
WantedBy=graphical-session.target

Enable and start it:

systemctl --user enable wayvnc
systemctl --user start wayvnc

Step 4: Connect from your computer

Install TigerVNC on your laptop or desktop. On macOS, brew install tiger-vnc works. On Ubuntu, use sudo apt install tigervnc-viewer. Enter the Pi's IP address (find it with hostname -I on the Pi) and connect on port 5900.

Step 5: Secure the connection

wayvnc does not encrypt traffic by default. On a private home network this is generally acceptable, but if you need to reach the Pi from outside your LAN, wrap the connection in an SSH tunnel:

ssh -N -L 5900:127.0.0.1:5900 user@your-pi-ip

Then point your VNC client at localhost:5900. The SSH layer handles encryption and authentication.

Give your OpenClaw Pi agent persistent cloud storage

Free 50 GB workspace with no credit card required. Push agent output to Fastio, search it with built-in AI, and share results with your team through the MCP server.

Start 14-Day Trial

With VNC working, you can install OpenClaw on the same Pi and use the graphical desktop to monitor the agent when needed. OpenClaw runs as a lightweight gateway service, and the OpenClaw Raspberry Pi install guide covers the supported hardware. The Pi handles orchestration, scheduling, and state persistence while AI models run remotely through cloud API calls to providers like Anthropic or OpenAI.

Hardware compatibility

The OpenClaw documentation lists these supported configurations:

• Pi 5 (4 GB or 8 GB): best option
• Pi 4 (4 GB): recommended
• Pi 4 (2 GB): functional with swap configured
• Pi 3B+ (1 GB): works but noticeably slow
• Pi Zero 2W: not supported

A 64-bit Raspberry Pi OS install is mandatory. 32-bit builds will not work.

Install steps

From your VNC session or SSH terminal:

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential

Install Node.js 24, which OpenClaw requires:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

If your Pi has 2 GB of RAM or less, configure swap before proceeding:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Install OpenClaw:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

Verify the agent is running:

openclaw status
systemctl --user status openclaw-gateway.service

Accessing the OpenClaw dashboard

The OpenClaw docs recommend SSH tunneling for dashboard access rather than exposing the port directly to your network:

ssh -N -L 18789:127.0.0.1:18789 user@your-pi-ip

Open http://localhost:18789 in your browser. Through VNC, you can also reach this directly on the Pi's desktop browser at http://127.0.0.1:18789.

Agent configuration and workspace state live in ~/.openclaw/. Create periodic snapshots with openclaw backup create to guard against SD card failures.

Running an OpenClaw agent on a Pi creates a practical storage problem. Agent output, logs, and artifacts sit on the Pi's SD card or USB drive. SD cards are not designed for heavy write cycles, and if you need to share agent output with collaborators or clients, local-only storage becomes a bottleneck quickly.

Several options can move files off the Pi:

• rsync to a NAS or remote server: simple and reliable, but you are maintaining another machine and there is no built-in sharing or search layer
• S3 or cloud object storage: scales well, but adds complexity around credentials, bucket policies, and access control for non-technical collaborators
• Cloud workspace with AI indexing: gives you file management, sharing, and semantic search in a single layer

Fastio takes the third approach. Its Business Trial includes 50 GB of storage, 5 workspaces, and included credits with no credit card required. The piece that matters for a Pi agent setup is the MCP server at mcp.fast.io, which exposes tools for file upload, workspace management, and AI-powered search through a protocol that agent frameworks can consume directly.

When your OpenClaw agent produces output, it can push files to a Fastio workspace where your team reviews them through a browser. Intelligence Mode, Fastio's built-in RAG layer, auto-indexes uploaded files for semantic search and chat with citations. You can ask questions about the agent's output and get answers that point back to specific documents and passages.

The ownership transfer feature is worth knowing about for client work. An agent can build out a workspace with deliverables, then transfer full control to a human who reviews and distributes the results. The agent retains admin access for future updates while the human becomes the owner.

For setup details, see the Fastio agent storage guide or the MCP skill documentation.

Black screen after connecting

The Pi is not rendering a desktop because no physical display is detected. Add the framebuffer resolution settings to /boot/firmware/config.txt as described in the wayvnc setup section, then reboot. On some Pi 4 boards, you may also need to add hdmi_force_hotplug=1 to force display output regardless of whether a monitor is plugged in.

Connection refused on port 5900

wayvnc may not have started, or the graphical session target has not been reached yet. Check with systemctl --user status wayvnc. If the Pi boots to a command-line interface instead of the desktop, wayvnc will not start because there is no graphical session to share. Switch to desktop boot using sudo raspi-config under System Options, then Boot / Auto Login, and select Desktop Autologin.

Laggy or stuttering display

Drop the framebuffer resolution to 1280x720 if you set it higher during initial setup. Disable desktop animations and compositing effects in the Raspberry Pi Desktop preferences. If you are running both OpenClaw and VNC on a Pi 4 with 2 GB of RAM, you may see memory pressure during heavy agent workloads. Check memory usage with free -h and consider adding more swap space or upgrading to a 4 GB board.

wayvnc fails to start after an OS update

Bookworm updates occasionally change Wayland session behavior. Verify that wayvnc is still installed with which wayvnc. Check whether the systemd unit file at ~/.config/systemd/user/wayvnc.service is intact and the graphical session target is active. Running loginctl show-session helps diagnose whether a Wayland session exists for your user.

Securing VNC on a shared or public network

Never expose port 5900 directly to the internet. The SSH tunneling approach from the setup section encrypts all traffic between your computer and the Pi. For persistent remote access without managing SSH sessions manually, Tailscale's free plan supports up to 100 devices and creates an encrypted mesh network with zero port forwarding required.