zero-desktop

GitHub Tag GitHub Workflow Status

A full Linux desktop environment in your browser. Zero installation required.

Run a complete LXDE desktop directly from your browser using only Docker. Perfect for demos, education, testing, and remote development.

Note: Add screenshot or GIF here showing the desktop in action

Why zero-desktop?

The problem: You need a Linux environment but don’t want to deal with VMs, complex installations, or time-consuming configurations.

The solution: One Docker command and 30 seconds later you have a complete Linux desktop accessible from any browser.

Key benefits:

Zero friction: One command and you’re in
Universal access: Works in any modern browser, no VNC clients needed
Portable: Carry your entire environment in a container
Ephemeral or persistent: Use Docker volumes to keep your work
Multi-architecture: Supports AMD64 and ARM64 (Raspberry Pi, Apple Silicon)

Quick start

Basic usage

docker run -d \
  -p 6080:6080 \
  -e VNC_PASS=yourpassword \
  ghcr.io/zero-desktop/zero-desktop:latest

Open your browser at http://localhost:6080

Note: This project is distributed via GitHub Container Registry (ghcr.io) only. Not available on Docker Hub.

Note: This image is designed for browser access only. For direct VNC client access, use zero-desktop-lxde.

With Docker Compose

services:
  desktop:
    image: ghcr.io/zero-desktop/zero-desktop:latest
    ports:
      - "6080:6080"
    environment:
      - SYSTEM_USER=docker
      - VNC_PASS=yourpassword
      - RESOLUTION=1920x1080

With persistent workspace

services:
  desktop:
    image: ghcr.io/zero-desktop/zero-desktop:latest
    ports:
      - "6080:6080"
    volumes:
      - ./workspace:/home/docker/workspace
    environment:
      - SYSTEM_USER=docker
      - VNC_PASS=yourpassword

Configuration

Variable	Default	Description
`SYSTEM_USER`	`docker`	Linux user for desktop session
`VNC_PASS`	Required	VNC password
`RESOLUTION`	`1280x720`	Screen resolution (WxH)
`ALLOW_NOPW`	`false`	Disable password (not recommended)

Installing additional software

After connecting, open a terminal:

sudo apt update
sudo apt install firefox-esr chromium git nodejs npm
refresh-menu

The refresh-menu command updates the desktop menu with newly installed applications.

Use cases

Education and training

Deploy identical Linux environments for students without requiring local installations. Share a single URL and everyone has access to the same setup.

# Deploy multiple instances for a classroom
for i in {1..30}; do
  docker run -d \
    -p $((6080+i)):6080 \
    -e VNC_PASS=student${i} \
    --name desktop-student${i} \
    ghcr.io/zero-desktop/zero-desktop:latest
done

Visual UI testing in CI/CD

Run end-to-end tests requiring a real browser with a graphical environment.

# .github/workflows/e2e-tests.yml
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      desktop:
        image: ghcr.io/zero-desktop/zero-desktop:latest
        ports:
          - 6080:6080
        env:
          VNC_PASS: test123
    steps:
      - name: Run visual tests
        run: |
          # Your test commands here
          npm run test:e2e

Software demonstrations

Show your application running in a clean Linux environment without asking users to install anything.

Remote development environment

Create a consistent development environment that can be accessed from anywhere, with all your tools pre-installed.

services:
  devenv:
    image: ghcr.io/zero-desktop/zero-desktop:latest
    ports:
      - "6080:6080"
    volumes:
      - ./projects:/home/docker/projects
      - ./ssh:/home/docker/.ssh:ro
    environment:
      - VNC_PASS=yourpassword
      - RESOLUTION=1920x1080

Comparison with alternatives

Feature	zero-desktop	Webtop	KasmVNC	Apache Guacamole
Browser-only access	✅	✅	✅	✅
Single container	✅	✅	✅	❌ (requires multiple services)
Setup time	< 1 min	< 1 min	~2 min	~10 min
ARM64 support	✅	✅	❌	✅
Lightweight	✅	❌	✅	❌

Architecture

zero-desktop combines several technologies:

LXDE: Lightweight desktop environment
TigerVNC: VNC server for remote display
noVNC: HTML5 VNC client for browser access
websockify: WebSocket proxy for VNC connection
Debian: Stable base system

Performance tips

For better performance:

Adjust resolution to match your screen: -e RESOLUTION=1920x1080
Use wired connection instead of WiFi when possible
Close unused applications inside the desktop
Consider using direct VNC client for high-bandwidth scenarios (see zero-desktop-lxde)

Security considerations

Always set a strong VNC_PASS
Don’t expose port 6080 directly to the internet without additional security (use reverse proxy with HTTPS)
Consider using a firewall to restrict access
For production use, implement proper authentication and encryption

Example with Traefik reverse proxy:

services:
  desktop:
    image: ghcr.io/zero-desktop/zero-desktop:latest
    environment:
      - VNC_PASS=yourpassword
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.desktop.rule=Host(`desktop.yourdomain.com`)"
      - "traefik.http.routers.desktop.tls=true"

Troubleshooting

Black screen after login

Wait 10-15 seconds for the desktop to initialize
Check container logs: docker logs <container-name>

Can’t connect to localhost:6080

Verify container is running: docker ps
Check if port is already in use: netstat -an | grep 6080
Try a different port: -p 8080:6080

Slow performance

Reduce resolution: -e RESOLUTION=1280x720
Close unnecessary applications
Check CPU/memory usage: docker stats

Applications not appearing in menu

Run refresh-menu after installing new software
Restart the desktop session

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache License 2.0 - See LICENSE file for details.

zero-desktop-lxde - Version with direct VNC client support

Acknowledgments

Built with:

This site is open source. Improve this page.