SPICE (Simple Protocol for Independent Computing Environments)

Introduction

SPICE (Simple Protocol for Independent Computing Environments) is an open remote computing solution built for virtual environments which allows users to view a computing “desktop” environment.

The integrating of Spice into Proxmox VE (PVE) provides a solution for interaction with virtualized desktop devices, like keyboard, mouse, audio and video. Interaction between front-end and back-end is done using Virtual Device Interfaces (VDI).

Spice achieves a user experience similar to an interaction with a local machine. It is suitable for both LAN and WAN usage, without compromising on the user experience.

Requirements for SPICE

In order to use Spice you need the following:

Spice client on your desktop OS
Spice drivers inside your VM (VirtIO, QXL Graphic card drivers)
Proxmox VE (PVE) networking configuration for SPICE (Simple Protocol for Independent Computing Environments)

Proxmox VE (PVE) networking configuration for SPICE (Simple Protocol for Independent Computing Environments)

To forward SPICE console traffic in Proxmox VE (PVE) for remote or external access, you must configure networking and firewall rules to handle the specific port and protocol used by the SPICE proxy.

Essential Port Configuration

The primary port for SPICE in Proxmox is TCP 3128. Target: The SPICE proxy service runs on the Proxmox host itself, not the individual VM. Action: Open or forward TCP port 3128 from your external gateway or firewall to the internal IP of the Proxmox host.

Implementation Methods

Depending on your network architecture, use one of the following methods:

Port Forwarding (Router/Gateway)

Redirect external traffic on port 3128 to your PVE host’s internal IP. Note that the .vv file downloaded from the PVE web interface often uses the hostname or IP as it appears to the server; if your external IP/FQDN differs, the client may fail to connect.

Example Details: RouterOS Port Exposing from LAN to WAN

Reverse Proxy (NGINX/Traefik)

Since SPICE uses a custom protocol (not standard HTTP), your proxy must handle TCP stream forwarding at Layer 4.

nginx: Use the stream module (e.g., libnginx-mod-stream) to forward raw TCP traffic.
traefik: Configure a TCP router with the CONNECT method matcher.

SSH Tunneling

For a more secure approach, create an SSH tunnel from your client to the Proxmox host for port 3128.

PVE Firewall Rules

If the Proxmox VE Firewall is enabled, you must explicitly allow this traffic. Navigate to Datacenter > Firewall or Node > Firewall. Add an IN rule: Direction: In Action: ACCEPT Protocol: TCP Dest. Port: 3128 Ensure the firewall is active at the Datacenter level.

VM Hardware Setup

SPICE must be enabled for the specific virtual machine to function. Go to the VM’s Hardware tab. Set Display to SPICE (qxl). Increase Memory (e.g., 32 MiB) to support higher resolutions.

SPICE client

Use a SPICE-compatible viewer like Remote Viewer (part of the Virt-Viewer package). Warning: The .vv configuration file generated by Proxmox is time-sensitive and will expire if not opened within approximately 40 seconds.

Install the client on your computer

Linux

Arch Linux

Using virt-viewer
```
paru -S virt-viewer nmap
```

Ensure the VM is configured for SPICE

In Proxmox VE (PVE) GUI (for the VM): Hardware → Display: set to SPICE (and use a SPICE-friendly video device such as QXL for best experience). Adding a QXL video device is a common requirement for good SPICE graphics.

On the Proxmox node: confirm it’s listening

SSH into the Proxmox node

Check the port is bound

sudo ss -lntp | grep ':3128'

Make sure the SPICE proxy port is reachable

Proxmox’s SPICE proxy listens on TCP 3128. So, from your client machine to the Proxmox node, you generally need:

3128/tcp reachable for SPICE console connections.

(Separately, you still use 8006/tcp for the Proxmox web UI, but that’s not the SPICE data path.)

nmap -Pn -p 3128 pve.yanboyang.com
 
Starting Nmap 7.98 ( https://nmap.org ) at 2026-01-03 02:38 -0500
Nmap scan report for pve.yanboyang.com (172.27.135.44)
Host is up (0.0041s latency).
 
PORT     STATE SERVICE
3128/tcp open  squid-http
 
Nmap done: 1 IP address (1 host up) scanned in 0.56 seconds

NOTE:

Make sure STATE is open

Download a fresh SPICE (Simple Protocol for Independent Computing Environments) .vv file and connect

In Proxmox Web UI

Make sure the VM is running.
VM → Hardware → Display is set to SPICE (not “Default”/VNC).
VM → Console → choose SPICE and download a fresh .vv file.

On your client

remote-viewer ./pve-spice.vv

Boyang Yan

Explorer