Guides

Linux desktop with KasmVNC

Open the graphical desktop of a discovered Ubuntu or Linux instance from Cushy using KasmVNC: what to install on the server, which ports to open, how sign-in really works, and the optional Devolutions Gateway tunnel for privately-addressed hosts.

Windows instances get RDP through a gateway. Linux instances get a browser desktop instead: you install [KasmVNC](https://github.com/kasmtech/KasmVNC) on the server, tell Cushy where it listens, and the resource's Access tab gains Open desktop (KasmVNC) ↗.

You sign in to KasmVNC itself

KasmVNC authenticates users with HTTPS Basic authentication against its own password file, and it publishes no way to hand a browser a pre-authorized session. So Cushy opens the desktop in a new tab and you sign in there. Cushy never stores, sends or embeds your desktop password — and never puts one in a URL.

What you install on the server

KasmVNC is GPL-2.0 software published by Kasm Technologies. Cushy does not ship or redistribute it — you install it from Kasm's own releases onto your own host.

A desktop environment. KasmVNC renders a desktop; it does not provide one. sudo apt-get install -y xfce4 xfce4-goodies (or MATE, LXDE, …).
KasmVNC itself, from the releases page — pick the package for your distribution.
A KasmVNC user — this is the credential you will type in the browser.
A session on a display number, optionally started at boot by systemd.

bash

# 1. desktop environment
sudo apt-get update && sudo apt-get install -y xfce4 xfce4-goodies

# 2. KasmVNC (choose the .deb for your distro from the releases page)
wget <package_url>
sudo apt-get install ./kasmvncserver_*.deb
sudo adduser $USER ssl-cert     # then log out and back in for the group to apply

# 3. a user: -w grants mouse+keyboard, -o would grant administration
vncpasswd -u ops -w

# 4. a session on display :1  →  listens on tcp/8444
vncserver -select-de xfce
# or, to start it on boot:
systemctl --user enable --now kasmvncserver@:1

Where the port number comes from

KasmVNC's network.websocket_port defaults to auto, which is 8443 + the display number — so display :1 listens on 8444. Set it explicitly in /etc/kasmvnc/kasmvnc.yaml or ~/.vnc/kasmvnc.yaml if you prefer, and enter whatever you chose in Cushy.

Ports — what to open, and what to keep closed

Direction	Port	Purpose	Who must open it
Your browser → instance	tcp/8444	The KasmVNC web desktop itself	Only your operator network (VPN, tailnet, office) — or nobody, if you use the tunnel below
Gateway → instance	tcp/8444	The optional Devolutions Gateway tunnel	A security-group / NSG rule from the gateway host only
Operator → gateway	tcp/7171 (https)	Where `jetsocat` connects for the tunnel	Only if you use the tunnel
Anywhere → instance	tcp/8444	Not required — keep it closed to the internet.	—
Anywhere → instance	tcp/5900	Not used. KasmVNC is not a classic RFB/VNC server and legacy VNC viewers cannot connect to it.	—

Use a real certificate

The package installs a self-signed "snake-oil" certificate, so your browser will warn on first connection. Point network.ssl.pem_certificate / pem_key at a real certificate for the instance's name, or accept the warning knowingly. Cushy always builds an https:// URL — KasmVNC requires TLS by default (require_ssl: true).

Point Cushy at the desktop

Open the instance from Inventory, then the Access tab. A Linux instance shows a Linux desktop (KasmVNC) panel.
Choose Configure (you need the *manage cloud accounts* capability — Org Admin or SRE · Cloud Admin).
Set the port (default 8444). Leave everything else blank and Cushy uses the instance's discovered private address.
Set an explicit desktop URL only when KasmVNC sits behind a reverse proxy or a published hostname — for example https://desktop-web1.corp.example.
Save, then use Open desktop (KasmVNC) ↗.

The desktop opens in a new tab at https://<address>:<port>/. Your browser prompts for the KasmVNC user you created with vncpasswd. That is the whole flow — there is no second Cushy step.

When you cannot reach the instance directly

If the instance only has a private address and you are not on that network, use the optional tunnel. It needs the same Devolutions Gateway your organization already runs for RDP, plus the jetsocat CLI on your own machine (from the gateway's releases).

Click Open desktop (KasmVNC) ↗ — the panel then offers Download tunnel script.
Run the script. It forwards 127.0.0.1:8444 through the gateway to the desktop.
Browse to https://127.0.0.1:8444/ and sign in to KasmVNC as usual.

bash

# what the downloaded script runs (the token is minted per session)
jetsocat forward 'tcp-listen://127.0.0.1:8444' \
  'wss://gateway.corp.example:7171/jet/fwd/tcp/<session-id>?token=<TOKEN>'

Treat the downloaded script as a secret until it expires

It carries a gateway token scoped to exactly one destination, one session and a few minutes — but for that window it is a bearer capability. It contains no KasmVNC credential. Your browser will also warn about the certificate name, because it sees 127.0.0.1 while the certificate names the instance.

What you will see when something is missing

State	What Cushy shows
No desktop configured	An honest note plus Configure (admins), or "ask an admin" for everyone else
A Windows instance	No KasmVNC panel at all — Windows uses RDP
Operating system not discovered	No desktop panel. Cushy will not guess an operating system
No address discovered and no explicit URL	The save is refused with "a desktop URL cannot be derived"
No gateway, or a gateway with no provisioner key	The desktop link still works; the tunnel is offered as unavailable, with the reason
A pending Terraform draft	No desktop panel — nothing exists in the cloud yet

Security model

No credentials in Cushy. KasmVNC users live in ~/.kasmpasswd on your server. Cushy stores a port, an optional URL and an optional note — nothing else.
Nothing is exposed by Cushy. It never proxies the desktop; your browser (optionally via your own gateway) does the reaching.
Least privilege per tunnel. Each tunnel token names one destination, one session, a unique id, an expiry in minutes and — when you set a gateway Id — one gateway.
Scoped to you. The tunnel download is a signed capability pinned to your user, organization *and protocol*; another operator, another organization, or the RDP download route all get a 403 or 404.
Audited. remote.kasmvnc_configured, remote.kasmvnc_removed, remote.session_started and remote.session_launched record who opened what and when. Token values never appear in the audit trail.
Least exposure on the server. Give the KasmVNC user -w (write) rather than -o (owner) unless they must administer users.

Current limits

The KasmVNC sign-in is separate from Cushy's — KasmVNC publishes no pre-authorized session hand-off, and Cushy will not fake one.
Safari cannot connect directly to KasmVNC (it does not pass Basic-auth credentials on WebSocket connections). Use Chrome, Edge or Firefox.
The tunnel is a command you run locally; there is no in-browser relay.
Cushy does not detect whether KasmVNC is installed — you configure the target, and a wrong port shows as a browser error rather than a fabricated "ready" state.
One desktop target per instance. No session recording and no clipboard policy from Cushy — KasmVNC's own data_loss_prevention settings control that.