# linuxserver/docker-webtop: A Full Linux Desktop Behind a Browser Tab

> The LinuxServer.io Webtop images ship XFCE, KDE, MATE or i3 on Alpine, Ubuntu, Debian, Fedora or Arch and serve the desktop over HTTP on port 3001. This is what the container actually contains, how to get a first session running, and where it stops being the right tool.

**linuxserver/docker-webtop** — Ubuntu, Alpine, Arch, and Fedora based Webtop images, Linux in a web browser supporting popular desktop environments.

- Repository: https://github.com/linuxserver/docker-webtop
- Stars: 4,415 · Forks: 379
- Language: Shell
- License: GPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/linuxserver-docker-webtop

## What docker-webtop actually gives you

The README describes the project as "Alpine, Ubuntu, Fedora, and Arch based containers containing full desktop environments in officially supported flavors accessible via any modern web browser." That sentence is the whole product. You are not installing a remote desktop client, and you are not exposing an X server over the network. You run a container, open a browser, and a desktop appears.

The audience is narrow and specific. It is for people who already run a home server or a small lab and want a Linux desktop they can reach from a laptop, a tablet, or a machine where they cannot install software. It is also for anyone who wants a disposable or reproducible desktop: the entire environment is defined by an image tag and a single volume.

The flavour matrix is the real feature. Version tags include alpine-i3, alpine-kde, alpine-mate, arch-i3, arch-kde, arch-mate, arch-xfce, debian-i3, debian-kde, debian-mate, debian-xfce, fedora-i3, fedora-kde, fedora-mate, fedora-xfce and ubuntu-i3, among others. The default latest tag is XFCE on Alpine. Choosing a tag is choosing both a distribution and a desktop shell, and those two choices are not independent: the README marks several combinations as Wayland Support or Wayland Only, so the compositor story changes with the tag.

## How the desktop reaches the browser

The Dockerfile is short and it tells you where the work happens. The image is built FROM ghcr.io/linuxserver/baseimage-selkies:alpine324. The desktop, the window manager and the browser-side streaming come from that base image, not from this repository. What docker-webtop adds is the desktop environment itself: for the default Alpine XFCE image, an apk add line pulls in xfce4, xfce4-terminal, thunar, mousepad, ristretto, chromium, adw-gtk3 and adwaita-xfce-icon-theme.

Two details in that Dockerfile are worth reading closely. First, the build moves /usr/bin/thunar to /usr/bin/thunar-real and then copies /root over the image, which means this repository's root directory supplies a wrapper or configuration for the file manager rather than the binary itself. Second, the build deletes /etc/xdg/autostart/xfce4-power-manager.desktop, /etc/xdg/autostart/xscreensaver.desktop and the power-manager panel plugin. Those are deliberate removals: a power manager and a screensaver make no sense in a session that has no physical display and should never blank.

The container exposes a single port, 3001, and declares a single volume, /config. That is the entire external surface. The desktop session, its settings and any files you keep inside the home directory live under /config, which is why that directory is the thing you back up and the thing you bind-mount. Everything else in the container is replaceable by pulling a new image.

## Running your first webtop container

The README points at lscr.io/linuxserver/webtop:latest as the image to pull, and notes that a plain pull retrieves the correct image for your architecture through the Docker manifest. The supported architectures listed are x86-64 and arm64, with arch-specific tags of the form amd64-<version tag> and arm64v8-<version tag>.

The LinuxServer.io convention of PUID and PGID controls which user the desktop process runs as, and TZ sets the timezone. A minimal docker run looks like this:

## Choosing a tag and a compose file

The latest tag is Alpine with XFCE. If you want Ubuntu with KDE, you change the tag, not the command. The README lists ubuntu-kde, ubuntu-i3 and ubuntu-lxqt among the Ubuntu variants, and the recent release tags follow the pattern ubuntu-lxqt-bc4eba3f-ls1 and ubuntu-kde-b838b944-ls180, so a specific build can be pinned if you want reproducibility rather than a moving latest.

A compose file is the more common way to run this, and it maps the same four settings. The service name and container name are yours to choose; the image tag is the only line that decides which distribution and desktop you get:

## Logging in and the port 3001 question

Once the container is up, you reach the desktop at http://<host>:3001 in a browser. The README does not document an authentication layer for that endpoint, and the Dockerfile exposes 3001 without any accompanying access-control configuration. Treat that as the project's sharpest edge: a desktop session on an open port is a remote shell for anyone who can reach it.

This is where the practical decisions happen. If the container is only reachable on a trusted LAN, the exposure is the same as any other unauthenticated service on that LAN. If it is reachable from the internet, the container itself does not appear to be the layer that protects it. The usual pattern is to put a reverse proxy with authentication in front of 3001, or to reach it only through a VPN. Neither of those is part of this repository; they are choices you bring.

The /config volume matters here too. Because the session's home directory and settings live there, the PUID and PGID you set should match the owner of the host directory you bind. If they do not, the desktop starts with a home directory it cannot write to, and the failure looks like a broken session rather than a permissions error.

## Where webtop is the wrong tool

The container is a full desktop, and that is the limitation. A desktop environment is a large amount of software running continuously whether or not anyone is looking at it. If what you actually need is one GUI application, such as a browser or a file manager, running the whole XFCE or KDE stack to get it is wasteful in both image size and memory. An application-specific container that exposes only that application is the better fit.

The second limitation is graphical performance. The Dockerfile for the default image installs chromium and the standard XFCE components, and nothing in the repository indicates GPU passthrough or hardware-accelerated rendering. The README's own framing is "accessible via any modern web browser," not "indistinguishable from a local desktop." For video playback, 3D work, or anything latency-sensitive, this is the wrong architecture, and no amount of tuning the container changes that.

The third is the multi-user case. The image declares one volume and one port. There is no documented notion of separate accounts inside one container. If you need several people to have isolated desktops, you run several containers, each with its own /config and its own port mapping, and you manage them individually.

## Alternatives and how they differ

The obvious comparison is a traditional remote desktop stack: a Linux host running a VNC or RDP server, with a native client on the machine you connect from. The difference is where the rendering and the client live. With VNC or RDP, the server exports a framebuffer or a remote display protocol and the client is a purpose-built application that you install. With webtop, the client is the browser you already have, and the container is the whole server. That means zero client installs and a session that is defined entirely by a Docker image and a volume, at the cost of depending on the browser's rendering path and on the container's networking.

A second alternative is running the desktop in a full virtual machine. A VM gives you a real kernel, real hardware abstraction and a real display stack, and it can run a desktop with GPU acceleration. The container cannot. The trade is operational: a VM image is measured in gigabytes and boots in tens of seconds, while a webtop container starts as a process and is replaced by pulling a new tag. If you need kernel modules, nested virtualization or hardware acceleration, the VM is the correct answer and webtop is not.

A third path is to skip the desktop entirely. If the goal is to reach files, a shell or a web application, a plain container running an SSH server or the application itself does the job with a fraction of the surface area. Webtop is worth its weight only when the graphical desktop is genuinely the thing you want.

## Maintenance, upgrades and the GPL

The repository is not archived, and the last push was on 2026-09-22, with release tags dated the same day. That is the maintenance signal available: the images are being rebuilt and tagged. The README also states that the LinuxServer.io team provides "regular and timely application updates" and "weekly base OS updates with common layers across the entire LinuxServer.io ecosystem to minimise space usage, down time and bandwidth." Those are the project's claims about its own cadence, not an independent measurement.

The upgrade model follows from the design. Because only /config is a volume, upgrading means pulling a newer tag and recreating the container; the desktop environment itself is replaced wholesale. The practical risk is that a new base image can change the desktop version underneath you, so pinning a specific tag such as ubuntu-kde-b838b944-ls180 is the way to make an upgrade a decision rather than a surprise. The cost of staying current is the pull and restart; the cost of pinning is that you own the decision to move.

The licence is GPL-3.0. That is a copyleft licence, and it governs the repository's own files, which are mostly Dockerfiles and the root overlay. It does not automatically tell you what obligations attach to the third-party packages installed inside the image, which carry their own licences. If you redistribute a modified image, the GPL-3.0 terms on this repository's files are the ones to read. None of this is legal advice; check with someone qualified before redistributing.

## Conclusion

Adopt webtop when you want a persistent Linux desktop reachable from a browser without installing a client, and when the desktop session itself is the deliverable, not a single application. Do not adopt it if you need GPU acceleration, a hardened multi-tenant remote-access product, or a thin client to one GUI app; use a dedicated remote desktop stack or an application-specific container instead. Before committing, verify which tag matches your distro and desktop choice, that port 3001 is reachable and protected on your network, and that your PUID and PGID match the owner of the host directory you bind to /config, because ownership of that directory is what the session inherits.

## FAQ

### What is docker-webtop?

It is a set of LinuxServer.io container images that package full desktop environments on Alpine, Ubuntu, Debian, Fedora or Arch and serve them to any modern web browser. The default latest tag is XFCE on Alpine, and the container exposes port 3001 with /config as its only volume.

### How does a webtop work?

The image is built on ghcr.io/linuxserver/baseimage-selkies, which provides the browser-side desktop streaming, while this repository adds the desktop environment packages such as xfce4, xfce4-terminal and thunar. The running container exposes port 3001, and you open that port in a browser to get the desktop.

### Which distributions and desktops does docker-webtop offer?

The version tag table lists Alpine, Arch, Debian, Fedora and Ubuntu images paired with i3, KDE, MATE, XFCE and, for Ubuntu, LXQT. The default latest tag is XFCE on Alpine, and several tags are marked as Wayland Support or Wayland Only in the README.

### How do I run docker-webtop with docker-compose?

Define a service with the image lscr.io/linuxserver/webtop:<tag>, set PUID, PGID and TZ as environment variables, bind /path/to/config to /config, and map port 3001. The image tag is what selects the distribution and desktop combination.

### Does docker-webtop need a GPU?

Nothing in the repository indicates GPU passthrough or hardware-accelerated rendering, and the default image installs ordinary XFCE components plus chromium. The README frames the product as a desktop accessible via any modern web browser, which is a statement about reach, not about graphics performance.

## Sources

- [Issues](https://github.com/linuxserver/docker-webtop/issues)
- [License: GPL-3.0](https://github.com/linuxserver/docker-webtop/blob/master/LICENSE)
- [linuxserver/docker-webtop on GitHub](https://github.com/linuxserver/docker-webtop)
- [README](https://github.com/linuxserver/docker-webtop/blob/master/README.md)
- [Releases](https://github.com/linuxserver/docker-webtop/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/linuxserver-docker-webtop