remote-viewer

View remote virtual machines or desktops

TLDR

View a remote using a virt-viewer file

$ remote-viewer [path/to/virt_viewer_file]

remote-viewer [OPTIONS] [URI | GUESTNAME]

Examples of URI/GUESTNAME:
guestname (Connect to a libvirt guest)
spice://host:port (Direct SPICE connection)
vnc://host:port (Direct VNC connection)
qemu:///system/guestname (Libvirt guest via URI)

PARAMETERS

--help, -h
    Displays a help message and exits.

--version, -V
    Shows the version information and exits.

--connect=URI
    Connects to the specified URI (e.g., qemu:///system/guestname, spice://host:port, vnc://host:port).

--direct
    Forces a direct connection to a VNC or SPICE server, bypassing libvirt resolution. Requires a --spice-uri or --vnc-uri.

--file=FILENAME
    Loads connection details from a virt-viewer (.vv) file. This file usually contains SPICE or VNC connection parameters.

--full-screen, -f
    Starts the viewer in full-screen mode. Press Shift+F11 to toggle.

--read-only
    Opens the remote display in read-only mode, disabling keyboard and mouse input.

--password=PASSWORD
    Specifies the password for the connection. Be cautious when using this on the command line due to security risks.

--no-verify-tls
    Disables TLS certificate verification. Use only in trusted environments or for testing, as it compromises security.

--spice-uri=URI
    Connects using a direct SPICE URI.

--vnc-uri=URI
    Connects using a direct VNC URI.

--clipboard=TYPE
    Sets the clipboard mode. Common values include auto (default), none, copy-paste, paste-copy.

--resize-to-guest
    Automatically resizes the viewer window to match the guest's display resolution (requires SPICE agent in guest).

DESCRIPTION

remote-viewer is a lightweight client application primarily used for connecting to virtual machine graphical consoles (SPICE, VNC) managed by libvirt, or directly to SPICE/VNC servers. It provides a highly interactive and responsive experience, especially with the SPICE protocol, offering features like audio redirection, clipboard sharing, and smart card pass-through. While often associated with QEMU/KVM virtual machines, it can connect to any generic VNC or SPICE server. It serves as the display component for the virt-manager tool but can also be used independently for quick and direct access to remote desktops.

CAVEATS

For optimal performance and features (like display resizing, clipboard sharing, and sound), ensure that the SPICE guest tools (e.g., spice-vdagent) are installed and running inside the virtual machine. Direct VNC connections may lack advanced features compared to SPICE. Using passwords directly on the command line can expose them in shell history or process listings, so consider more secure methods for production environments.

HISTORY

remote-viewer is an integral part of the virt-viewer project, which originated to provide a dedicated, high-performance display client for virtual machines managed by libvirt, specifically focusing on the QEMU/KVM hypervisor. Its development has closely tracked the evolution of the SPICE protocol, aiming to offer a rich remote desktop experience for virtualized environments on Linux. It spun off as a standalone executable to allow direct connections without the need for the full virt-manager GUI.