Skip to content

How-to guides

How to run a Linux desktop in the browser

Run a desktop on a virtual display with a VNC server, put noVNC in front of it, and open noVNC's page in any browser.

Updated · Facts checked · By Runtime Cloud

4 min read

Read as Markdown

On Runtime (withruntime.com), a desktop is one API call: a Linux desktop with Chromium in a Firecracker microVM, already running noVNC on port 6080. Share that port as a private preview and its link opens the live screen in a browser tab, with nothing to install on either side. The same machine answers screenshots and mouse and keyboard steps over the API, so a computer-use agent and a person can share one screen. At its default size, 2 vCPU and 4 GiB, a desktop costs $0.035 an hour while little runs on it (pricing).

The four parts of a desktop in a tab

A Linux server has no screen, so a desktop in the browser is built from four programs, each with one job:

Part Job A common choice
Virtual display An X server that draws into memory instead of a monitor Xvfb
Window manager Windows, title bars, focus Fluxbox, Openbox
VNC server Sends the display's pixels and takes input over RFB x11vnc, TigerVNC
WebSocket bridge and client Carries RFB over a WebSocket and draws it on a canvas websockify and noVNC

The browser loads noVNC's page, which opens a WebSocket to websockify. websockify passes the bytes on to the VNC server as plain TCP. Keys and clicks travel the other way. What is VNC? covers the protocol itself.

Build one yourself on Ubuntu

On Ubuntu 24.04 the four parts are all in the archive. These commands start a 1280 by 800 desktop with a VNC password, listening for VNC on the machine itself only:

Terminalsudo apt-get updatesudo apt-get install -y --no-install-recommends xvfb fluxbox x11vnc novnc websockifyXvfb :1 -screen 0 1280x800x24 &DISPLAY=:1 fluxbox &x11vnc -storepasswd 'choose-a-password' ~/.vnc-passwdx11vnc -display :1 -forever -shared -rfbauth ~/.vnc-passwd -localhost -rfbport 5900 &websockify --web /usr/share/novnc 6080 localhost:5900 &

Then open http://<host>:6080/vnc.html. -localhost keeps the VNC port off the network, so the only way in is through websockify. Put websockify behind HTTPS and a login before you open it to the internet: anyone who reaches the page can try the password, and VNC's own password check is weak (RFC 6143 says it is not meant for untrusted networks).

Start one on Runtime

A desktop starts with Chromium open and noVNC already listening. Share port 6080 as a private preview and open its link with the token on the end:

TypeScriptimport { writeFile } from "node:fs/promises";const api = "https://api.withruntime.com/v2";const headers = {  Authorization: `Bearer ${process.env.RUNTIME_API_KEY}`,  "Content-Type": "application/json",};async function call(method: string, path: string, body?: unknown) {  const res = await fetch(`${api}${path}`, { method, headers, body: JSON.stringify(body) });  if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${await res.text()}`);  return res;}const json = async (method: string, path: string, body?: unknown) =>  (await call(method, path, body)).json();const desktop = await json("POST", "/desktops", {});const preview = await json("POST", `/sandboxes/${desktop.id}/previews`, { port: 6080 });// Open this in a browser tab to watch, and to use the mouse and keyboard yourself.console.log(`${preview.url}vnc.html?runtime_preview_token=${preview.token}`);// Code drives the same screen: focus Chromium's address bar, type, press Return.const acted = await json("POST", `/desktops/${desktop.id}:act`, {  actions: [    { type: "key", keys: "ctrl+l" },    { type: "type", text: "https://example.com" },    { type: "key", keys: "Return" },    { type: "wait", ms: 1500 },  ],});console.log(acted.screen); // { width: 1280, height: 800 }const shot = await call("GET", `/desktops/${desktop.id}/screenshot`);await writeFile("screen.png", Buffer.from(await shot.arrayBuffer()));// When you are done: await call("DELETE", `/desktops/${desktop.id}`);

The page in the tab and the screenshot show the same screen, so a person can watch an agent work, step in, and hand back. The full list of steps an act takes, from click and drag to scroll and wait, is in the desktops guide.

Share it safely

  • Keep the preview private. A private preview needs its token, and the link above carries it, so share the link only with the people who should see the screen. Never share port 6080 as a public preview: anyone with the address could use the desktop.
  • Leave port 5900 closed. Runtime's desktop runs its VNC server on port 5900 inside the machine without a password, because the private preview is the way in. Do not open 5900 as a public TCP port.
  • Tokens end. Each token stops at the preview's tokenExpiresAt. The preview's sign call returns a new one, and ttlSeconds makes one shorter.

Common problems

Symptom Cause and fix
The link does not load at first noVNC was still starting, a second or two after the desktop: load it again
noVNC shows "Failed to connect to server" Self-built: websockify is not running, or points at the wrong VNC port
A black screen with a cursor Self-built: no window manager or program is running on the display; start one with DISPLAY=:1
Typed text lands in the wrong place Something else has focus: click the target first, or send a click step before type

Sources

Facts on this page were checked on 17 November 2026.

Cut your cloud billby 66%.

7 days of Pro for $0, and no card to sign up. Billed by the second after.

Start your free trial