How to Access Your Proxmox VE VM Console: noVNC, SPICE, and Serial Terminal Explained

Introduction

You click a VM in the Proxmox VE tree, hit the big blue Console button, and a screen pops up showing your virtual machine's desktop right there in the browser. Most new users never think about it twice. It just works, and that's kind of the point.

Then one day it doesn't. The screen goes black. Typing produces the wrong characters. Someone in a forum thread tells you to "just use SPICE instead," and you have no idea what that means or why your noVNC console suddenly isn't good enough. There's also a third option sitting quietly in a dropdown menu called xterm.js that nobody explains either.

None of this is complicated once you know what each piece actually does. This guide walks through all three console types Proxmox VE gives you, why you'd pick one over another, and the specific fixes for the console problems that trip up almost everyone at some point.

What You Will Learn

• What the Proxmox VE console actually is, and why it's separate from SSH or RDP
• The difference between noVNC, SPICE, and the xterm.js serial terminal
• How to switch a VM to SPICE and set up the Remote Viewer client on your own computer
• How to reach a VM's serial console from the command line with qm terminal
• Why your console sometimes shows a black screen, a garbled display, or the wrong keyboard characters
• Which console type actually makes sense for your situation

What Is This Feature?

The console in Proxmox VE is a direct window into a VM's virtual monitor, keyboard, and mouse — the same experience as sitting in front of a physical machine with a screen plugged in. It works completely independently of whatever operating system is running inside the VM, which matters more than it sounds like it should. If a Linux guest's network is misconfigured and SSH won't connect, or a Windows guest is stuck at a boot repair screen, the console still gets you in, because it doesn't rely on the guest's network stack at all.

Proxmox VE actually gives you three different ways to view that virtual screen, and each one is a genuinely different piece of technology under the hood:

noVNC is the default for a reason: it needs nothing beyond a browser, and it's what you get the instant you click Console on a fresh VM. It's based on VNC, an older remote-desktop standard, wrapped in enough JavaScript to run inside a web page.

SPICE (Simple Protocol for Independent Computing Environments) was built from the ground up for virtualization rather than adapted from something else. It handles things noVNC struggles with — smoother mouse movement, dynamic resolution changes, audio, and even sharing a folder from your computer into the VM. The tradeoff is that it needs a real application installed on whatever computer you're connecting from, since browsers can't speak the SPICE protocol natively.

The serial terminal is the odd one out because it isn't graphical at all. It shows text only, the way an old-school serial cable connection to a server would. This sounds like a downgrade, and for a desktop OS it is, but for a Linux server with no desktop environment, it's often the fastest and most reliable console you can get.

Why Would You Use It?

For most VMs, most of the time, the default noVNC console is genuinely fine. You wouldn't bother switching anything. But a few specific situations push people toward SPICE or the serial terminal instead.

• SPICE is worth the extra setup when you're doing anything interactive for a while — installing a Windows guest from scratch, working inside a Linux desktop environment, or needing copy-paste and folder sharing between your machine and the VM. The mouse tracking alone is noticeably better than noVNC over a slower connection.
• The serial terminal earns its place when you're managing a headless Linux server VM with no GUI, or when noVNC itself won't load because of a browser or network issue. It's also lighter on bandwidth, which matters if you're managing Proxmox over a slow VPN or a mobile connection.
• noVNC stays the right call for quick checks — glancing at a boot screen, running one command, checking whether a VM actually started. Firing up a separate desktop app for a ten-second look would be overkill.

I'd skip SPICE entirely for a VM you only ever manage over SSH. Installing a viewer app just to look at a console you'll never actually use isn't worth the five minutes it takes.

Prerequisites

• A Proxmox VE 8.x or 9.x host with at least one VM created
• Access to the Proxmox web interface, reachable at https://your-server-ip:8006
• PVEVMUser or higher permissions on the VM (root has this automatically)
• For SPICE specifically: a separate Windows, macOS, or Linux computer where you can install a small client application
• For the serial terminal via SSH: terminal access to the Proxmox host itself as root or a user with shell access

Step-by-Step Tutorial

Opening the Default noVNC Console

This one barely needs a walkthrough, but it's worth knowing what's happening behind the click.

1. Select a VM in the left-hand tree.
2. Click Console in the top toolbar, or the >_ Console entry in the resource tree.
3. A new browser tab or panel opens showing the VM's virtual screen, streamed live over a WebSocket connection to port 8006.

If the VM is running Linux with a desktop environment or Windows, you'll see it boot right there. If it's a minimal server install with no GUI, you'll see text scrolling by during boot, then a login prompt — which is exactly what the serial terminal shows too, just delivered a different way.

Switching a VM to SPICE

SPICE takes two separate setup steps: telling the VM to offer a SPICE display, and installing the client app on the computer you're connecting from.

Step 1: Set the VM's display type.

1. Shut the VM down, or at least be ready for the display to reset briefly.
2. Select the VM, go to Hardware, then double-click Display.
3. Change the Graphic card dropdown to SPICE, then click OK.
4. Start (or restart) the VM.

Step 2: Install Remote Viewer on your own computer.

SPICE needs a real client application, called virt-viewer (the app itself is named Remote Viewer). Browsers can't speak SPICE natively, which is the main reason noVNC exists as the zero-install default.

• On Windows or macOS, download the virt-viewer installer from the official virt-viewer project page and run it like any other application.
• On Debian or Ubuntu, install it from the terminal: sudo apt install virt-viewer
• On Fedora or other RPM-based distros: sudo dnf install virt-viewer

Step 3: Connect.

1. Back in the Proxmox web interface, click the small arrow next to Console and choose SPICE from the dropdown instead of the default noVNC option.
2. Your browser downloads a small .vv file — this isn't the VM's data, just a text file containing the connection details Remote Viewer needs.
3. Open that file. If your OS asks which application should handle it, pick Remote Viewer and, if it offers to remember the choice, let it.
4. Remote Viewer opens in a new window showing the VM's display, usually noticeably crisper and more responsive than noVNC was.

Optional: Turning on SPICE Enhancements

Once SPICE is working, a few extra features are worth enabling for guests you'll be working in regularly.

1. Select the VM, go to Options, then double-click SPICE Enhancements.
2. Enable Folder Sharing if you want to drag files between your computer and the VM.
3. Enable Video Streaming if the VM will be doing anything video-heavy over the SPICE connection.

For folder sharing to actually work inside the guest, install the matching agent: spice-vdagent on Debian or Ubuntu guests, or the SPICE agent bundled inside the virtio-win-guest-tools installer on Windows guests. Without that agent running inside the VM, the folder-sharing option in Remote Viewer's File menu just won't do anything.

Using the Serial Terminal (xterm.js) From the Web Interface

This one requires a bit of guest-side setup, since the guest OS itself has to know it should send its console output over a serial port instead of a virtual monitor.

Step 1: Add a serial port to the VM.

1. Select the VM, go to Hardware, click Add, then choose Serial Port.
2. Leave it as Serial Port 0 and confirm. Proxmox creates it as a socket-backed serial device by default.

Step 2: Tell the VM to use it as the display.

1. Double-click Display under Hardware.
2. Change the Graphic card option to Serial terminal 0.

Selecting a serial port as the display type turns off the regular VGA output entirely and redirects the web console to that serial port instead — so this step matters, not just the previous one.

Step 3: Configure the guest OS to output to the serial port. This is the step most tutorials skip, and it's why people end up staring at a blank xterm.js window. On a Debian or Ubuntu guest, enable a getty (login prompt) on the virtual serial line:

systemctl enable --now serial-getty@ttyS0.service

You'll also want the kernel itself echoing boot messages to that port. Edit /etc/default/grub and add a serial console entry to the kernel command line:

GRUB_CMDLINE_LINUX="console=tty0 console=ttyS0,115200n8"

Then apply it and reboot:

update-grub

After a reboot, clicking Console on that VM shows a real text terminal, boot messages and all, running entirely in the browser with no client software involved.

Reaching a Serial Console From the Command Line

If you're already SSH'd into the Proxmox host and don't want to open a browser at all, there's a direct CLI path. This works independently of whatever the VM's Display setting is currently set to, as long as a serial port device exists on the VM:

qm terminal 105

Replace 105 with your VM's ID. This attaches your SSH session directly to the VM's serial console. Press Ctrl+O to disconnect cleanly without shutting anything down — closing the terminal window instead can leave the connection in a stale state.

Commands Explained

Common Errors

• Black screen on noVNC that never changes. Usually means the VM hasn't actually finished booting yet, or the guest OS crashed silently during boot. Check the VM's Summary tab for a spike in CPU usage that then drops to zero, which often means it crashed rather than hung.
• "Failed to connect to server" in Remote Viewer. The .vv file has a short expiry window for security reasons. If you downloaded it and waited too long before opening it, just click SPICE again in Proxmox to generate a fresh one.
• Typing produces the wrong symbols in the console. This is almost always a keyboard layout mismatch. Check Datacenter → Options → Keyboard Layout and make sure it matches your actual keyboard, not just your OS language.
• xterm.js shows a completely empty black window, no cursor, nothing. The guest OS almost certainly isn't sending anything to the serial port yet. Revisit the serial-getty and GRUB steps above — this is the single most common cause.
• "remote-viewer: command not found" after opening the .vv file. The virt-viewer package isn't installed, or your OS doesn't have it associated with .vv files. Install it and try opening the file again.

Troubleshooting

If noVNC loads but shows a spinning connection indicator that never resolves, check that port 8006 is actually reachable from wherever you're browsing from — a firewall rule or VPN split-tunnel configuration blocking that port produces exactly this symptom, and it has nothing to do with the VM itself.

If SPICE connects but the display looks stretched or the wrong resolution, install the guest agent tools mentioned earlier. Without spice-vdagent on Linux or the SPICE driver from virtio-win-guest-tools on Windows, SPICE falls back to a fixed resolution instead of dynamically matching your Remote Viewer window size.

If qm terminal connects but shows nothing no matter what you type, double-check the VM actually has a serial port configured under Hardware — the command will connect successfully even to a VM with no serial device, it just won't show any output because there's nothing on the other end.

For Windows guests, don't expect the serial terminal to show anything useful. Windows doesn't send its boot process or a login prompt to a serial port without extra configuration (Special Administration Console, or SAC, which is its own separate setup). For Windows VMs, stick to noVNC or SPICE.

Best Practices

• Leave noVNC as the default for VMs you rarely touch directly — there's no reason to add SPICE setup overhead for something you check twice a year.
• Set up SPICE early for any VM you'll be actively working inside for more than a few minutes at a time, like a desktop Linux VM or a Windows install you're customizing by hand.
• Configure the serial console on headless Linux server templates once, then clone from that template — every VM built from it inherits working serial console access automatically.
• Don't leave sensitive VMs with an open console session unattended in a browser tab. Anyone with access to that browser session has full keyboard and mouse control over the guest, same as sitting at a physical machine.

Frequently Asked Questions

Can I use the console instead of setting up SSH entirely?

Technically yes, but you shouldn't rely on it long-term. SSH supports multiple simultaneous sessions, scripting, and file transfer. The console is really meant for the situations where SSH isn't an option, like a network misconfiguration or a boot problem.

Does SPICE work over the internet, or only on a local network?

It works over the internet the same way the web interface does, though a slow or high-latency connection will feel it more than noVNC would, since SPICE is pushing a richer video stream.

Why does my console session disconnect when I close my laptop?

Sleeping or losing network on your end drops the connection, but the VM itself keeps running untouched. Reopen the console and you're right back where you left off.

Is one console type more secure than another?

All three run over Proxmox's existing TLS-encrypted connection to port 8006, so none of them is meaningfully less secure than the others. The real security question is who has permission to open the console at all, which comes down to your user permissions setup.

Can I copy and paste between my computer and the VM?

SPICE supports clipboard sharing once the guest agent is installed. noVNC's clipboard support is more limited and inconsistent across browsers. The serial terminal, being text-only, generally supports basic copy-paste through your browser's own selection.

Conclusion

Three console types sounds like more than you need until the moment your usual one doesn't work, and suddenly it's exactly what saves you. noVNC covers the day-to-day glance, SPICE earns its keep for anything hands-on, and the serial terminal turns into the most reliable option the instant a VM's graphical output can't be trusted.

Set up SPICE on the VMs you actually work inside, get the serial console configured on your Linux server templates once, and you'll rarely find yourself stuck looking at a black screen with no idea what to try next.