docker-ros2-desktop-vnc puts a ROS 2 desktop in the browser

A browser-based desktop for a framework that assumes a screen

The problem is that ROS 2 tooling, and much of the simulation work around it, assumes a graphical environment, while the machines that run ROS 2 are often headless servers, containers or embedded boards. docker-ros2-desktop-vnc solves that by assembling an Ubuntu desktop with ROS 2 inside a container and serving it through an HTML5 VNC interface, so the whole desktop is reachable from a browser. The project describes itself as Dockerfiles to provide an HTML5 VNC interface to access Ubuntu Desktop and ROS 2, and it is explicitly based on AtsushiSaito's docker-ubuntu-sweb project, which supplies the VNC and desktop machinery. The intended user is a robotics developer who needs Gazebo, a GUI tool or a desktop terminal on a machine that has no display attached.

One container, one port, and a shared memory size to get right

The quick start is a single docker run command, and the two parameters that matter are the port mapping and the shared memory size. The image is pulled from GitHub Container Registry with a distribution tag, port 6080 on the host is mapped to port 80 in the container, and the shared memory size is set to 512m with the README saying to change that value depending on the situation:

docker run -p 6080:80 --shm-size=512m ghcr.io/tiryoh/ros2-desktop-vnc:lyrical

The shared memory setting is the one people get wrong, and it is not obvious from the command alone why it is there. It exists because the VNC server has to render a desktop into a memory area the container can share, and too small a value produces a blank or broken screen rather than a clear error. After the run, the README says to browse to the loopback address on port 6080, and the local images are also on Docker Hub under a different registry name, so you can choose which one to pull from without changing the rest of the command.

Gazebo and VSCodium break until seccomp is turned off

The failure mode is documented rather than hidden, and it is worth reading before you decide this project fits. Some GUI applications do not work correctly when their system calls are blocked by Docker's default seccomp profile, with the reported symptoms being Gazebo displaying a blank window and VSCodium failing to launch, and the README notes this may also occur with Docker Desktop on macOS. The fix is to retry with the seccomp profile disabled, adding a security option to the run command:

docker run -p 6080:80 --security-opt seccomp=unconfined --shm-size=512m ghcr.io/tiryoh/ros2-desktop-vnc:lyrical

There is a warning attached to that workaround, and it is not a formality. Disabling seccomp removes Docker's default system call filtering and reduces container isolation, and the README says to update Docker Engine or Docker Desktop first and to use the workaround only when necessary with a trusted image. The history is also given, since the workaround was first introduced for an incompatibility between a newer glibc in the container and older Docker seccomp implementations, and later became needed for GUI blackout issues.

Five distributions are built, and the tree holds more

The images are per distribution, and the CI table shows a build badge for each of five: Humble, Iron, Jazzy, Lyrical and Rolling. Rolling is the development distribution, so a tag that tracks it is a moving target in a way the others are not. The repository tree holds a directory per distribution plus a few extras, with dashing, eloquent, foxy, galactic, humble, iron, jazzy, kilted, lyrical and rolling directories, and separate arm64 directories for dashing and galactic. Some of those directories are for older distributions that the CI table does not list, which tells you the tree has accumulated history and that not every directory is currently built. The project is published to two registries, Docker Hub as tiryoh/ros2-desktop-vnc and GHCR as ghcr.io/tiryoh/ros2-desktop-vnc, with the README tracking pull and download counts for both, all time and per week and per month.

Building locally means a directory per distribution and a tag per target

Building from source is a per-distribution operation, and the README gives the three forms for each: a plain docker build for the native architecture, then a docker buildx build for linux/amd64 and another for linux/arm64, each with its own tag suffix. Taking the Jazzy example, the three commands are:

cd jazzy && docker build -t tiryoh/ros2-desktop-vnc:jazzy .
# using "docker buildx" (amd64)
cd jazzy && docker buildx build --platform=linux/amd64 --progress=plain -t tiryoh/ros2-desktop-vnc:jazzy-amd64 .
# using "docker buildx" (arm64)
cd jazzy && docker buildx build --platform=linux/arm64 --progress=plain -t tiryoh/ros2-desktop-vnc:jazzy-arm64 .

The buildx invocations pass the platform and use plain progress output, and the tags carry an architecture suffix so a multi-architecture setup can distinguish them. The repository also contains a docker-bake.hcl file, which is the natural way to drive the same matrix for all distributions at once, and a .github/ directory holding the per-distribution deploy workflows that the CI badges point at. The .chglog/ directory suggests changelog entries are generated rather than written by hand, and the presence of a .coderabbit.yaml and a .gemini/ directory shows the project has been wired into automated review tooling.

A related ROS 1 project and official upstream images

Two pointers in the README tell you where this sits in the ecosystem. The first is the ROS 1 version, a separate repository, docker-ros-desktop-vnc, which is the same idea applied to the older distribution. The second is a link to the official ROS 2 Docker images maintained by Open Robotics, with a note that those exist. That comparison is the interesting one for anyone deciding what to use. The official images are the reference for running ROS 2 itself, headless and node oriented, and this project adds a desktop and a browser VNC layer on top of that idea. If your workflow is building nodes and running them in CI, the official images are the simpler answer. If you need to see a simulator or drive a GUI tool, that is what this repository is for.

The homepage is a Japanese blog post, and that is the documentation

One thing to be aware of is where the documentation actually lives. The homepage in the repository metadata points at memoteki.net, and the README says the details of these tools are written in Japanese on that page, with the link to the article. The README itself is short and the linked article is the real documentation, which is a reasonable arrangement for a project maintained by a Japanese robotics developer with a long-running blog, but it does mean a reader who does not read Japanese is dependent on the README for anything beyond the commands. The repository structure otherwise looks well run, with a CHANGELOG.md, a CONTRIBUTING.md, a CODE_OF_CONDUCT.md and a Japanese variant of the code of conduct, a LICENSE file, and the .chglog/ directory for changelog generation. The licence is Apache-2.0, which is permissive and well suited to redistribution of derived images.

Editorial conclusion

docker-ros2-desktop-vnc suits a ROS 2 developer who needs a graphical environment on a headless machine, on a remote server, or on a platform without a native desktop, and who is content to work in a browser rather than a local X session. It does not suit a production deployment that needs container isolation intact, since the documented fix for broken GUI applications disables the seccomp profile entirely. Before deploying, try the default run first, since the seccomp workaround reduces container isolation and the README warns to use it only when necessary with a trusted image, and note that the last push to the repository was on 2026-10-19 with no GitHub releases published.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. Tiryoh/docker-ros2-desktop-vnc on GitHub