Connecting to a Virtual Desktop


You must be able to forward a port.

A virtual desktop provides a graphical interface to using the cluster. Desktops are hosted withing Singularity containers, so not all of the NeSI software stack is supported. If you would like to build your own desktop containers with the code here.

Rendering is done cluster-side, and compressed before being sent to your local machine. This means any rendering should be significantly more responsive than when using X11 on its own (approximately 40 times faster).


The Virtual desktops are still in development, please report any issues to NeSI support, or open an issue here.


Port Forwarding

A port on your local machine must be forwarded to Mahuika.

Learn about setting up port forwarding

For example:

ssh -L 1234:localhost:1234 mahuika


Port numbers should be between 1025-49151. It's OK to use the same number for local and remote ports (makes it easier to remember too!)

Add VDT to path

Run the command.

echo "export PATH="/opt/nesi/vdt/:\$PATH"">>~/.bash_profile;. ~/.bash_profile

to add the VDT command to your path, if you don't do this step you can still use the vdt command as /opt/nesi/vdt/vdt


vdt -h for general help or vdt [command] -h for help relating to that command.

vdt start [port] vdt start 4321 Starts a desktop session on the login node. It will last until the shell is closed.
  vdt start -p 4321 Starts a desktop session on the login node. It will continue running after you disconnect.
  vdt start -p -r wbg005 4321 Starts a desktop session on another  node. It will continue running after you disconnect.
vdt list vdt list Lists all your persistent sessions.
vdt kill vdt kill name Kills desktop [name].



Recommend setting scaling to 'remote'


The conditions for running a desktop on the login node are similar to when using a shell. There are no time limits, but should not be used for large or long running jobs. Any serious amount of computation should be launched with SLURM, this can be done using the terminal or GUI. 

In the case where your work needs to be run interactively, and cannot be managed from a different node, you can launch the desktop on a compute node 

On the login node

You may run desktops on the login node, provided you are not doing any serious computation there.

Once on Mahuika, enter in the path to the desktop followed by your forwarded port (--help for more options).

vdt start [port]

Then in a web browser navigate to your forwarded address. e.g.


On a compute node

If you plan on doing computation in the desktop instance, you should be doing it on a compute node. If the -r [hostname] flag is set an attempt will be made to start the desktop there. You must have an allocation on the chosen node in order to launch there. This could be an all-ready running job, or a new salloc session.

vdt start -r [hostname] [port]


salloc --nodes 1 --cpus-per-task 8 --time 01:00:00 vdt start 1234

If running inside a Slurm session, hostname will be inferred from environment (unless explicitly set).

Was this article helpful?
1 out of 1 found this helpful