WLEDashboard

A high performance, local first control surface for WLED devices. Control 1 to 100+ LED controllers from a single responsive interface with spring physics animations, group management, and automatic mDNS network discovery.

Explore the full dashboard, device controls, 3D spatial floorplans, and simulated OTA firmware updates in an in-memory virtualized hardware sandbox with zero physical microcontrollers attached.

Safely evaluate features, test multi-room configurations, and flash virtual firmware with complete isolation. Real physical devices and database records remain hidden and untouched while exploring the sandbox.

Control all your WLED devices with real time power toggles, dynamic brightness sliders with responsive color glow, anti-aliased conic-gradient color wheel pickers, four corner symmetrical hardware and action chicklets, and live telemetry headers.

Organize devices into physical zones, synchronized scenes, and custom lighting clusters. Control group power, group brightness, and group colors simultaneously with automatic device command distribution.

Easily build and customize lighting groups with custom color palettes, group type classifications (Zone, Scene, Sync, Custom), device member selection, and nested child group clustering.

Automate lighting based on fixed times or astronomical sunrise/sunset triggers (suncalc). Build multi-step routine timelines with custom delay intervals between step actions.

Experience your lighting in 3D space with Three.js and React Three Fiber. View procedural room geometries, wireframe wall bounds, and real-time emissive LED light strips that pulse and glow matching actual device color and brightness. Includes a stunning holographic Earth orbital sequence.

Browse WLED built-in effect catalogs, build custom multi-track keyframe animation timelines, design multi-stop color gradients, and simulate light patterns on a live 60-pixel LED strip canvas.

In-depth documentation hub integrated directly into the application with interactive tables, mobile installation instructions, group synchronization mechanics, and Home Assistant setup guides.

Install WLEDashboard directly to your mobile home screen on iOS and Android for a seamless full-screen native experience without browser navigation bars or address controls.

Restore exactly what you need from any backup with per category opt in checkboxes covering devices, groups, presets, settings, automations, spatial layouts, and studio content. A dependency validator keeps parent references coherent by skipping orphaned child records automatically, in both merge and replace modes.

• Local First Architecture: SQLite storage with WAL journal mode. Zero cloud dependency, zero external account required, all data stays on your local network.
• Automatic Device Discovery: mDNS network scanning (_wled._tcp) automatically discovers WLED controllers on your local network and populates MAC addresses, firmware versions, and LED counts.
• 3D Spatial Viewport: WebGL 3D canvas powered by Three.js & React Three Fiber. Render 3D floor plans, spatial light anchors, and real-time emissive light strip meshes.
• Spring Physics Motion: Dynamic damped harmonic oscillator spring engine drives interactive UI controls, toggle switches, hover elevations, and card transitions.
• Group Management & Nesting: Organize controllers into Zone, Scene, Sync, or Custom groups. Support for nested child groups and concurrent group command execution.
• Automation & Schedules Engine: Astronomical sunrise/sunset calculations (suncalc), time-based schedules, step-by-step routine timelines, and a 30s background scheduler loop.
• Dashboard Group Clustering: Instant toggle between individual device grid view and group cluster cards for high density setups.
• JSON Configuration Backup: Full export and import capabilities for backing up, restoring, or transferring dashboard state and device configurations.
• Fastify & WebSocket Backend: Fast Node.js API server with low latency WebSocket connection pushing live WLED state updates instantly to all connected clients.
• Docker Ready: Multi stage Docker container support with host networking for seamless local network mDNS multicast discovery.

+-------------------------------------------------------------+
|                      WLEDashboard Web                       |
|   (Vite + React 19 + Zustand + Spring Physics Engine)       |
+------------------------------+------------------------------+
                               |
                               | HTTP / WebSocket
                               v
+-------------------------------------------------------------+
|                      WLEDashboard API                       |
|   (Fastify + SQLite WAL + mDNS Discovery + Polling Engine)  |
+------------------------------+------------------------------+
                               |
                               | LAN JSON API (/json/state)
                               v
+-------------------------------------------------------------+
|                     WLED Controllers                        |
|        [Device 1]       [Device 2]       [Device 3+]        |
+-------------------------------------------------------------+

WLEDashboard provides pre-built container images published to the GitHub Container Registry (ghcr.io/upioneer/wledashboard:latest). To ensure a consistent, zero-configuration environment across all operating systems, deployment via Docker Compose is the recommended installation method.

Create a docker-compose.yml file (or use the one included in the repository root):

services:
  wledashboard:
    image: ghcr.io/upioneer/wledashboard:latest
    container_name: wledashboard
    restart: unless-stopped
    ports:
      - "8301:8301"
    volumes:
      - wledashboard_data:/app/data
    environment:
      - NODE_ENV=production

volumes:
  wledashboard_data:

Start the container in detached mode:

docker compose up -d

docker run -d \
  --name wledashboard \
  -p 8301:8301 \
  -e NODE_ENV=production \
  -e PORT=8301 \
  -e DATA_DIR=/app/data \
  -v wledashboard_data:/app/data \
  --restart unless-stopped \
  ghcr.io/upioneer/wledashboard:latest

Access the application in your browser at http://localhost:8301.

• Persistence: All configuration, groups, and device states persist in the wledashboard_data volume mounted to /app/data.
• Local Discovery: Standard bridge port mapping routes web traffic on port 8301 (preventing collisions with Z-Wave JS UI, Grafana, or Uptime Kuma). On Linux bare metal hosts or LXC containers where mDNS broadcast discovery across subnets is required, network_mode: host can optionally be configured.

To update to the latest release without losing any configuration or database records:

docker compose pull && docker compose up -d

• Preserving Bookmarks: If upgrading from versions prior to v0.21.0 and you wish to keep browser bookmarks on port 3001, map 3001:8301 under the ports section in your docker-compose.yml.
• Automated Updates with Watchtower (Opt-In): The included docker-compose.yml provides a commented com.centurylinklabs.watchtower.enable=true label. Uncomment this label if you run Watchtower and wish to automate background container updates.

Deploy WLEDashboard as an unprivileged Debian 12 LXC container on Proxmox VE with automated systemd service management and dedicated bridge networking:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/upioneer/WLEDashboard/master/install/proxmox/wledashboard.sh)"

• Turnkey Execution: Provisions an LXC container with 1 CPU core, 2048MB RAM, and 1024MB Swap for build headroom (runtime consumption is only ~45MB to 90MB).
• Native Service: Runs as a managed systemd service (wledashboard.service) listening on port 8301 with auto-restart on boot.
• Direct Host Shell Access: Drop into the container root shell from your Proxmox host via pct enter <CTID> (or connect to serial console via pct console <CTID>).
• Ad-Hoc Host Commands: Execute commands directly without entering the container using pct exec <CTID> -- <command>.
• One-Command Container Updates: To update the LXC installation in the future, run pct exec <CTID> -- update-wledashboard from the Proxmox host shell.

• MagicPlan / Polygon Floorplan Imports: Interpret complex geometric shapes, L-shaped rooms, and non-rectangular walls to accurately reconstruct advanced 3D spatial layouts from popular floorplan apps.
• Community Preset Hub: Browse, download, and share custom pixel art and dynamic WLED effect presets with the community.
• Multi-Instance Dashboard Sync: Synchronize configuration across multiple browser tabs and devices in real-time.

Copyright (c) 2026 Jasen Henry. All Rights Reserved.

WLEDashboard is proprietary software. You are welcome to deploy, self-host, and run WLEDashboard for personal, non-commercial home automation.

• No Redistribution: Copying, mirroring, redistributing, or publishing the source code, container images, or binaries without explicit written permission is strictly prohibited.
• No Unauthorized Modifications: Creating public derivatives, unauthorized forks with modifications, or redistributed builds is not permitted under the copyright terms.
• Terms & Inquiries: For full legal provisions, review LICENSE.md. For commercial licensing or inquiries, please contact the repository owner.