Docs/Getting started
Getting started

Connect to your Spark's VNC desktop

By Samuel Seidel · Updated September 23, 2026 · 5 min read

This guide connects you to a graphical desktop on your instance, from the browser or from a native VNC client on Linux, macOS or Windows. VNC is optional and off by default: you turn it on when you deploy, and GPUwerk generates the username and password for you.

You need: an instance deployed with Enable VNC desktop access checked, with status running. VNC cannot be switched on for an existing instance; deploy a new one with the box checked. No SSH key is needed unless you use the SSH tunnel.

On this page
  1. Find your connection details
  2. Linux
  3. macOS
  4. Windows
  5. A note on security
  6. Tunnel it over SSH instead

1. Find your connection details

  1. Open the instance in the console.
  2. In its Connect section, find VNC desktop. It shows an address (host:port), a username and a password. They stay available there for as long as the instance exists.
  3. For the quickest route, click Open in browser there. The desktop opens in the page; no client to install.

For a native client, use the address exactly as shown. On an instance with its own public IPv4 (the normal case) the port is 5900; on an older shared-gateway setup it is a port specific to your instance. Below, <address> and <port> mean those two values.

No VNC desktop section? VNC was not enabled at deploy time. Deploy a new instance with the box checked; a rebuild does not add it.

2. Linux

TigerVNC's viewer is the most common client and packaged on most distributions:

# Debian, Ubuntu
sudo apt install tigervnc-viewer
vncviewer <address>:<port>

# Fedora
sudo dnf install tigervnc
vncviewer <address>:<port>

Result: the viewer asks for the password from the console, then shows the desktop. For a graphical client, Remmina ships in most distro repositories: add a new connection, protocol VNC, server <address>:<port>, and enter the password when prompted.

3. macOS

No install needed. macOS's built-in Screen Sharing speaks VNC. Either:

open vnc://<address>:<port>

Or, without the terminal: in Finder choose Go → Connect to Server (⌘K), enter vnc://<address>:<port> and click Connect.

Result: Screen Sharing asks for the password, then opens the desktop in a window.

4. Windows

Windows has no built-in VNC client. Either of these free viewers works:

5. A note on security

VNC's own authentication and screen traffic are not encrypted by default. The password exchange and everything you see and type over a direct VNC connection can be read by anything positioned to observe the connection between you and the instance. This is a property of the VNC protocol itself, not something specific to how GPUwerk runs it.

A direct connection is fine for quick, low-sensitivity work such as running a GUI installer or checking a render preview. For anything else, use the browser viewer (it runs over HTTPS) or tunnel the connection over SSH as shown below, which encrypts it and authenticates it with your SSH key.

6. Tunnel it over SSH instead

This needs your own SSH key on the instance (see the SSH keys guide).

  1. Forward the VNC server's port through SSH. Inside the container it always listens on 5900, whatever port the console shows for direct access:
    # -N means "no shell, just the tunnel"
    ssh -N -L 5900:localhost:5900 root@my-instance.gpuwerk.com
  2. Leave that running. The command prints nothing while the tunnel is open.
  3. Point your VNC viewer at localhost:5900 and enter the same generated password.

Result: the desktop opens, and the VNC traffic travels inside the encrypted SSH connection.

See alsoCreate an SSH key and connect to your Spark See alsoUse the in-browser terminal Back toAll docs
First top-up: pay $20, get $30 in credit

Open a desktop on your own Spark.

A dedicated DGX Spark in Europe, North America or East Asia, through the console.

Create account