Virtual Desktop

Defined intabs.hcl

The virtual_desktop resource adds a tab that shows a VM’s graphical desktop. Users work in it with their mouse and keyboard, copy and paste text between the desktop and their own computer, and, when audio is on, hear the VM’s sound. Use it for software that needs a screen, such as desktop applications or a graphical installer.

A VM gets a display only when a virtual desktop targets it, so VMs without one keep running headless.

HCL Syntax

Basic Syntax

resource "virtual_desktop" "desktop" {
  target = resource.vm.workstation
}

Fields

Field	Type	Required	Description
target	referencevm	✓	Select the VM to show. A VM gets a display only when a virtual desktop targets it.
audio	bool	—	Turn this on when the lab needs sound from the VM. The learner unmutes it in the tab. Defaultfalse

Guest Requirements

The display, mouse and keyboard need no software in the guest beyond a graphical desktop: the VM gets a virtio GPU and a USB tablet, whose drivers are in every mainstream Linux kernel. Clipboard sharing and sound need a little more:

• Clipboard: the guest needs spice-vdagent, which most desktop images include. Without it, the desktop still works, but copy and paste stay inside the VM.
• Sound: the guest needs the snd-hda-intel driver and a sound server (e.g. PipeWire or PulseAudio). Desktop images include both. Ubuntu cloud kernels ship the driver in the linux-modules-extra package.

The screen starts at 1920 × 1200 and is scaled to fit the tab. Desktops that follow display changes (e.g. GNOME on Wayland) also resize to the tab; others keep that resolution.

Validation Rules

• Target: target must reference a vm resource. Containers have no display to show.
• One viewer per desktop: a VM’s display has one viewer at a time. When a user opens the desktop in another window, that window takes it over, and the first one offers to take it back. This holds across resources too: two virtual_desktop resources on the same VM share one display, so opening either takes it from the other.

Examples

Desktop with sound

Sound is off by default. With audio on, the VM gets a sound card, and users turn the sound on with the speaker icon in the tab’s header.

resource "vm" "workstation" {
  image {
    name = "my-team/ubuntu-desktop:v1"
  }

  resources {
    cpu    = 2
    memory = 4096
  }
}

resource "virtual_desktop" "desktop" {
  target = resource.vm.workstation
  audio  = true
}

Add the virtual desktop to a layout tab to surface it to users.