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.
Note
Default Port Relocation (v0.21.0+): Default application networking has moved from port 3001 to port 8301 to eliminate port collisions with common homelab services such as Z Wave JS UI, Grafana, and Uptime Kuma.
- New Deployments: Access WLEDashboard directly at
http://<host-ip>:8301. - Existing / Upgrading Installations: Update the
portsmapping in yourdocker-compose.ymlto"8301:8301". - Preserving Existing Port 3001 Bookmarks: If you wish to retain existing browser bookmarks, Home Assistant dashboard links, or reverse proxy routes on port 3001, map host port 3001 to container port 8301 in your
docker-compose.yml:ports: - "3001:8301"
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, flat hairline cards tinted by live color, live LED preview bars, brightness sliders, color wheel pickers, hardware and action chips, and live telemetry headers. Unreachable devices render uniform marching ants with crisp names.
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.
Design custom 3D physical lighting installations across 8 geometric topologies including cone trees, rings, spheres, arches, and spirals. Preview real-time LED string routing, visualize muted structural scaffolding, and calculate accurate power injection and wire gauge requirements.
Explore 50 authentic WLED effect simulations on a pinned live 60-pixel LED strip canvas, toggle between multi-column cards and compact dropdown/list view, design custom 2D matrix artwork with zoom and eraser controls, and compose multi-track keyframe timelines.
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.
Keep server time visible with a live clock in the sidebar footer, configurable in three styles and any display timezone. The Time & Clock settings section shows the server clock that drives schedules and automations, which follow the host NTP synchronized clock on every platform with no separate setup.
Turn any LED matrix into a scrolling text sign with up to 10 rows of per row colored text in a crisp 3x5 pixel font, live scroll preview with speed and direction controls, serpentine wiring support for zigzag panels, one click DDP push to real controllers, and savable marquee presets that reload from the gallery.
Force a live state read past every cache with one click from any device card menu. The new refresh endpoint polls the controller directly and resyncs the dashboard, with honest feedback when a device is unreachable.
Store reusable LED panels with size, target device, and serpentine wiring, then recall the whole setup in one click from the marquee tab. Saved matrices make pushing scrolling signs to known hardware instant, with honest unbound states when a device is removed.
Pick a device or group target once, then click any effect card, row, palette, color, or slider to preview it on real hardware immediately with no Apply step. The primary color rides along so lights match the simulator, Keep changes and Restore now live beside the picker with the sandboxed device names, and Reset preview reselects Solid while restoring every touched light.
Every effect card grid, compact row list, dropdown, palette, device, group, and timezone picker now sorts A to Z with natural number ordering, so Strip 2 lands before Strip 10 and large collections stay scannable.
The 60 pixel simulator now matches real WLED firmware behavior verified against upstream source. Dynamic renders stepped random rainbow confetti, Android shows its primary window over a palette gradient, Chase Random steps its background per sweep, and Running and Saw use exact wave counts.
The 3D Objects tab now speaks the same design language as the rest of the app, with standard cards, inputs, violet primary actions, and a spring Toggle for the structure guide, wrapped around the same live LED layout preview and power blueprint.
Dress the whole dashboard shell in one of seven subtle ambient patterns, from Aurora glow to Matrix rain. Color follows a custom pick or live device and group state, motion respects reduced motion settings, and the treatment shows on every view including Studio.
Pull the friendly name stored on each WLED controller into the dashboard with one click. Select specific devices or sync them all from the new Settings section, with honest per device reporting when a controller is unreachable or returns an empty name.
Chain controllers into continuous 1D runs where patterns travel from member to member over DDP. Ranges are hard bookended by firmware LED counts, the swap button reverses travel direction per member, and playback carries fallback snapshots with auto resume.
- 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 -ddocker 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:latestAccess the application in your browser at http://localhost:8301.
- Persistence: All configuration, groups, and device states persist in the
wledashboard_datavolume 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: hostcan 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:8301under the ports section in yourdocker-compose.yml. - Automated Updates with Watchtower (Opt-In): The included
docker-compose.ymlprovides a commentedcom.centurylinklabs.watchtower.enable=truelabel. 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
systemdservice (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 viapct 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-wledashboardfrom 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.