One-ClickGitHub
Home / Documentation / VPS Console & Temporary Web VNC
VPS Access

VPS Console & Temporary Web VNC

Recover a KVM guest from the terminal or open a short-lived graphical console in your browser, even when its normal network access is unavailable.

One-Click documentation · Fleet-managed KVM access

Serial Console — Direct Terminal Access

Use the serial console when guest networking or SSH is not responding. One-Click resolves the VM in the virtualization inventory, locates its Fleet hypervisor and attaches to its libvirt serial console.

one-click --console mix
# Connected to domain 'mix'
# Escape character is ^] (Ctrl + ])

Use Ctrl + ] to detach from the guest console. The guest must have a usable serial console configured. This is host-side console access; it does not require the guest's SSH service or public IP.

Temporary Web VNC — Graphical Recovery

For a VM with an active graphical VNC display, open a temporary noVNC/websockify browser viewer. One-Click resolves the owning hypervisor, creates a controller-side SSH tunnel to its display and produces a time-limited session URL.

one-click --vnc mix
one-click --vnc mix 1200  # Optional duration, in seconds

The default session duration is 600 seconds (10 minutes). When prompted, choose yes to restrict viewer access to a specific IP address. If One-Click cannot determine your SSH client's address after switching users, enter the browser's actual public source IP manually. An empty address must never result in an unrestricted rule.

Protect Temporary Console Sessions

The browser URL contains a bearer token. Treat it as sensitive, do not share it or include it in public logs, and close the session when finished. The current example workflow may return an http:// link rather than HTTPS; avoid traversing untrusted networks with that URL. Prefer an IP restriction and a trusted encrypted access path.

What Happens on a Remote Fleet Hypervisor

  1. The controller identifies the target VM and its owning hypervisor from the VPS and Fleet inventories.
  2. For --console, it opens a libvirt serial-console connection on that hypervisor.
  3. For --vnc, it finds the guest's graphical display and creates a loopback SSH tunnel to it.
  4. It requests optional access control for the temporary viewer and applies the appropriate firewall rule.
  5. The temporary web proxy presents the browser session and cleans up its token, ports and tunnel after expiration.

Troubleshooting

No serial outputCheck that the guest operating system enables a serial console and that the VM has a libvirt serial device.
No active graphical displayVerify the guest has an active VNC graphics device and inspect the hypervisor's virsh vncdisplay result.
SSH client IP unavailableThis is common after sudo, su, or within tmux. Supply the browser client's actual IP explicitly when restricting the viewer.
Browser viewer cannot connectCheck the controller's session listener, temporary firewall rule, SSH tunnel, timeout and client IP restriction. Avoid permanently opening the temporary port.
← KVM & VPS GuideConsole Command Reference →