Experimental Lab

Run Debian in the browser

Spin up a Debian environment with WebAssembly emulation or streamed desktops. This page outlines practical ways to try it without leaving the portal.

Open GNOME desktop Choose an approach
What to expect

Heavy builds or Docker-in-Docker are out of scope; lean on WebAssembly or remote desktops for heavier workloads.

Live desktop

Full Debian GNOME session from the portal

Host a Debian GNOME desktop with noVNC and open it inline so phones, tablets, and laptops get the same experience. Pair it with a reverse proxy on your domain to keep the session inside this portal.

🚀

Bring your own Debian GNOME

The linuxserver/webtop:debian-gnome image ships with a GNOME desktop and noVNC. Expose it behind HTTPS so the embed below can connect from anywhere.

  1. 1

    Start the container

    docker run -d --name debian-gnome -e PUID=1000 -e PGID=1000 -e TZ=UTC \ -p 3000:3000 -v /opt/webtop:/config ghcr.io/linuxserver/webtop:debian-gnome

  2. 2

    Secure and publish

    Put a reverse proxy (Caddy, Nginx, or Traefik) in front of 3000 with HTTPS and an auth gateway. Mobile browsers need HTTPS to allow iframes and clipboard support.

  3. 3

    Embed inside the portal

    Point the embed URL to your proxy. Visitors stay on the portal while interacting with GNOME through noVNC, including touch controls on Android.

Tip: set WEBSOCKET_COMPRESSION=false if you run through a VPN or slow network to reduce latency.

🪟

Open your GNOME session here

Drop the public HTTPS address for your webtop container. We load it in an iframe so it behaves like a native portal app.

The URL should point to the root of the webtop/noVNC page (default port 3000).

Your GNOME desktop will appear here once you supply the URL. This area is touch friendly for mobile; pinch and drag gestures map to the remote desktop.

Ways to try

Pick the approach that fits your demo

Choose between a WebAssembly VM that runs entirely in the browser or a streamed desktop session. Both keep visitors inside the portal experience.

🧩

WebAssembly VM (v86)

Use the open-source v86 emulator to boot a lightweight Debian image directly in the browser. Ideal for terminal-first demos.

  • Fetch a prebuilt .wasm bundle and disk image
  • Mount a persistent file system via IndexedDB
  • Expose a serial console for interactive shell access
Open v86 Debian demo See integration steps
🖥️

Streamed desktop (noVNC)

Host Debian on a small VM or container and relay its desktop through noVNC. Great for showcasing graphical apps without heavy client downloads.

  • Start an x11vnc or TigerVNC server on the host machine
  • Proxy traffic through a WebSocket-compatible endpoint
  • Embed the noVNC client in this portal for seamless access
noVNC project Review constraints
🧭

Hosted snapshot

Use a pre-recorded session or guided walkthrough when interactivity is not required. Keep bandwidth low while still showing the Debian flow.

  • Capture asciinema or short WebM clips for key tasks
  • Offer downloadable configs and disk images
  • Pair with transcripts so content is searchable
Record with asciinema Add to this directory

Build in this repo

Drop in a v86-powered Debian lab

Keep assets self-contained so the experience works from static hosting. The steps below outline a minimal integration that can be iterated later.

  1. 1

    Bundle assets

    Place the v86.wasm, supporting JS, and a small Debian disk image in /debian-browser/assets/. Prefer compressed, read-only images to keep load times low.

  2. 2

    Wire up the emulator

    Initialize V86Starter with the local assets, attach to a canvas, and expose the serial console in this page. Keep the configuration in a dedicated JS module to simplify future tweaks.

  3. 3

    Persist user files

    Map /home to an IndexedDB-backed file system using IDBFS or the built-in v86 browserfs layer so sessions survive page reloads.

  4. 4

    Streamline controls

    Add keyboard shortcuts for common actions (reset, screenshot, copy/paste) and keep them documented near the canvas for discoverability.

  5. 5

    Test offline

    Serve the directory locally with npx serve debian-browser and confirm the emulator loads without network access once assets are cached.

Constraints

What to keep in mind

Browser-hosted operating systems are resource-intensive. Plan around visitor network conditions and keep recovery paths visible.

Performance

WebAssembly emulation is CPU heavy. Favor minimal Debian images, avoid background daemons, and provide a pause button for laptop users.

Storage

IndexedDB quotas vary by browser. Clearly show how much space an image consumes and provide a one-click reset to reclaim storage.

Security

Keep all assets static and signed. Avoid mounting untrusted disk images and make sure any remote desktop endpoints require authentication.