# Configuring Desktop Sessions

> Source: https://parallelworks.com/docs/run/sessions/desktops/configuring-desktop-sessions

# Configuring Desktop Sessions

This page is for the people who own a cluster's definition. It covers how desktop sessions start on a node, what the node needs, and the **Desktop session configuration** settings that control the desktop your users get. For launching and using a desktop, see [Desktop Sessions](/docs/run/sessions/desktops).

## How a desktop starts

When a user launches a desktop, the ACTIVATE agent on the target node:

1. Downloads the desktop software from the platform (once per node, then cached), verifying each download against the platform's signed software manifest.
2. Starts a VNC server (TigerVNC's `Xvnc`) on a free display. The desktop resizes to fit the user's browser window.
3. Starts a desktop environment inside it, either from an Apptainer/Singularity container or from what is installed on the host (see [Choosing the desktop environment](#choosing-the-desktop-environment)).
4. Streams the display to the user's browser through ACTIVATE. Nothing on the node needs to accept inbound connections from the user.

The desktop runs as the user, with the user's home directory, groups, and file permissions.

<MermaidDiagram chart={`
%%{init: {"theme": "neutral", "sequence": {"mirrorActors": false}} }%%
sequenceDiagram
    participant B as User's browser
    participant P as ACTIVATE
    participant A as Agent on the node
    B->>P: Launch desktop
    P->>A: Start desktop session
    A->>P: Download desktop software (first launch only)
    P-->>A: Signed TigerVNC bundle, fallback WM, XFCE image
    A->>A: Start Xvnc, then the desktop (Apptainer XFCE or host desktop)
    A-->>P: Session running
    B->>P: Open desktop
    P->>A: Relay VNC stream
    A-->>B: Desktop in the browser
`} />

### Where software is installed

| Agent runs as | Install location |
| --- | --- |
| root | `/opt/pw/software/<name>` |
| a regular user | `~/.cache/pw/software/<name>` (or `$XDG_CACHE_HOME/pw/software/<name>`) |

The downloads are a TigerVNC bundle (`Xvnc` plus the libraries, keyboard maps, and fonts it needs), a small fallback window manager (fluxbox and xterm), and, only when Apptainer mode is on, the platform's default XFCE container image.

## Node requirements

- **Linux.** Desktop sessions aren't supported on macOS hosts.
- **Host libraries.** The bundled `Xvnc` needs `libgbm.so.1` and `libxshmfence.so.1`, and TigerVNC 1.13 or later also loads `libxcvt.so.0`. Install them if your nodes lack them:

  | Library | RHEL / Rocky | Debian / Ubuntu |
  | --- | --- | --- |
  | `libgbm.so.1` | `mesa-libgbm` | `libgbm1` |
  | `libxshmfence.so.1` | `libxshmfence` | `libxshmfence1` |
  | `libxcvt.so.0` | `libxcvt` | `libxcvt0` |

  If the bundled `Xvnc` can't run, the agent falls back to a system-installed `Xvnc`. On RHEL 8 family hosts (RHEL, Rocky, Alma, CentOS, Oracle Linux 8) the agent prefers the system `Xvnc` when one is installed.
- **Apptainer mode only:** `apptainer` or `singularity` must be on the `PATH` or available through `module load`.
- **GPU rendering only:** see [GPU-accelerated rendering](#gpu-accelerated-rendering).

## Desktop session configuration

Desktop settings live on the cluster's **Definition** page, in the collapsed **Desktop session configuration** section. The section is available on cloud clusters and existing (on-premises) clusters. [Managed clusters](/docs/compute/managed-clusters/planning-and-setup) don't have this section; instead, an administrator picks the **Session Node** that hosts desktops.

![Screenshot of the Desktop session configuration section with Apptainer, a SIF path, bind paths, an init script, and GPU-accelerated rendering set.](/content-images/docs/run/sessions/desktops/desktop-session-configuration.png?v=df2e5bba)

You can change these settings while the cluster is running. New desktop sessions use the updated settings; sessions that are already open keep the settings they started with.

| Setting | What it does |
| --- | --- |
| **Use Apptainer/Singularity** | Runs the desktop (XFCE) inside an Apptainer/Singularity container instead of using the desktop installed on the host. Off by default. |
| **SIF file path** | Absolute path to a pre-staged `.sif` image on the cluster, for example `/p/app/parallelworks/xfce.sif`. Leave blank to use the platform default. Shown only when Apptainer is on. |
| **SIF overlay paths** | Apptainer `--overlay` paths layered onto the SIF, mounted read-only. Use when the SIF is a small stub image and the content lives in a separate squashfs. Existing clusters take a single **SIF overlay path**. Shown only when Apptainer is on. |
| **Bind paths** | Host paths to mount into the desktop container, one per row. Labeled **Bind Path** on existing clusters. Shown only when Apptainer is on. |
| **Init script** | A shell snippet that runs inside the desktop session before the desktop starts. Runs in both Apptainer and host modes. |
| **GPU-accelerated rendering (VirtualGL)** | Renders OpenGL applications on the node's NVIDIA GPU instead of in software. Off by default. |

These settings travel with the cluster when you publish it to the [Marketplace](/docs/marketplace).

### Choosing the desktop environment

There is no desktop picker: the environment depends on whether Apptainer is on.

**Apptainer on.** Every session runs XFCE from the container image, so all users get the same, reproducible desktop regardless of what is installed on the node. The agent picks the image in this order:

1. The **SIF file path**, if set and readable.
2. The platform-default XFCE image, downloaded and cached on the node.

If a node can't mount SIF images (common on STIG- or CIS-hardened systems), the agent unpacks the image into a sandbox directory and runs that instead.

**Apptainer off.** The agent uses the first desktop it finds installed on the host, in this order:

1. XFCE (`xfce4-session`)
2. MATE (`mate-session`)
3. Cinnamon (`cinnamon-session`)
4. GNOME (`gnome-session`)
5. LXDE (`startlxde`)
6. LXQt (`lxqt-session`)
7. KDE Plasma (`startplasma-x11`)
8. The bundled fluxbox window manager, or a host-installed openbox, fluxbox, IceWM, or twm
9. A bare `xterm`

To give users a particular host desktop, install it (and uninstall or avoid ones earlier in the list).

:::tip Per-user startup
A user can take over desktop startup entirely by creating an executable `~/.vnc/xstartup.custom`. The agent regenerates `~/.vnc/xstartup` on every launch, so don't edit that file.
:::

### Bind paths

The container always mounts the user's home directory, plus the X11 socket, `$XAUTHORITY`, and `$XDG_RUNTIME_DIR`. Add the shared file systems your users need (project directories, scratch, software trees):

```text
/scratch
/p/app:/opt/apps
/datasets:/datasets:ro
```

- `/host/path` mounts at the same path inside the container.
- `/host/path:/container/path` mounts it at a different path.
- Append `:ro` to mount read-only.

Each entry is passed to Apptainer's `--bind` option. If the host path doesn't exist on a node, the agent skips it rather than failing the session. Bind paths have no effect when Apptainer is off, because the host desktop already sees the host's file systems.

### Init script

Use the init script for setup every desktop session needs, for example:

```bash
module load matlab paraview

# Add site applications to the desktop menu
mkdir -p ~/.local/share/applications
ln -sf /p/app/desktop-entries/*.desktop ~/.local/share/applications/
```

### The desktop terminal in Apptainer mode

In Apptainer mode, the desktop's terminal opens on the cluster host, so users see the host `PATH`, modules, scheduler commands, and installed software. To get a shell inside the desktop container instead, users open **Container Terminal** under **Applications → System**.

## GPU-accelerated rendering

By default, desktops render in software, which is fine for most work but slow for 3D visualization. With **GPU-accelerated rendering (VirtualGL)** on, OpenGL applications render on the node's NVIDIA GPU through VirtualGL's EGL back-end. You don't need a 3D X server or `vglserver_config`.

Every node that may host a desktop needs:

- An NVIDIA GPU and driver (`nvidia-smi -L` must succeed).
- VirtualGL installed, with `vglrun` on the `PATH` (`dnf install VirtualGL` on RHEL and Rocky).
- Access to the GPU render node (`/dev/dri/renderD*`) for the user running the session, typically through the `render` or `video` group.

The agent re-checks these on every session start. If anything is missing, the session still starts with software rendering, and the agent logs why (see [Troubleshooting](#troubleshooting)). In Apptainer mode the agent also passes the GPU into the container (`--nv` and `/dev/dri`) and runs VirtualGL inside it.

## Custom desktop wallpaper

Organization administrators can set the wallpaper every new desktop session shows. See **Desktop Wallpaper** in [Customizing Organization Theme](/docs/organization-admin/customize/theme#desktop-wallpaper).

## Troubleshooting

Desktop logs are written to the user's `~/.vnc` directory on the node that ran the session:

| File | Contains |
| --- | --- |
| `~/.vnc/xvnc-<display>.log` | The VNC server: startup, missing libraries, crashes |
| `~/.vnc/xstartup-<display>.log` | Desktop startup: which desktop was chosen, bind or overlay paths skipped, init script output |
| `~/.vnc/xfce-*.log` | XFCE components (Apptainer mode) |

The agent's own log records the GPU decision on every launch as `VNC GPU rendering decision`, with a `mode` (`accelerated` or `software`) and a `reason`.

| Symptom or message | Cause and fix |
| --- | --- |
| _this cluster requires Apptainer or Singularity for desktop sessions, but neither was found on this node_ | Apptainer mode is on, but the node has neither command. Install one, make it available through `module load`, or turn off **Use Apptainer/Singularity**. |
| _Desktop (VNC) sessions are not supported on macOS_ | The target is a macOS host. Use a Linux node. |
| _neither bundled nor system Xvnc is usable_ | The bundled `Xvnc` can't run on this node and no system `Xvnc` is installed. Check `xvnc-<display>.log` for the missing library and install it (see [Node requirements](#node-requirements)), or install TigerVNC from your distribution. |
| `libxcvt.so.0`, `libgbm.so.1`, or `libxshmfence.so.1` _missing from host and bundle_ | Install the library listed in [Node requirements](#node-requirements). |
| _X display not ready after 10s timeout, Xvnc may have crashed_ | The VNC server didn't come up. Check `xvnc-<display>.log`. |
| A desktop with only a terminal or a bare window manager | Apptainer is off and no full desktop is installed on the host. Install XFCE (or another desktop), or turn on Apptainer. |
| A shared directory is missing inside the desktop | Add it to **Bind paths**. Check `xstartup-<display>.log` for _cluster bind path missing on host, skipping_. |
| GPU decision `reason` is `no_nvidia_device` or `nvidia_smi_failed` | The NVIDIA driver isn't loaded on this node, or the node has no GPU. |
| GPU decision `reason` is `vglrun_missing` | Install VirtualGL on the node. |
| GPU decision `reason` is `no_egl_device` | The user can't reach `/dev/dri/renderD*`. Add users to the `render` or `video` group. |
| GPU decision `reason` is `disabled_by_cluster` | **GPU-accelerated rendering (VirtualGL)** is off in the cluster definition. |