Add the visual display editor to Home Assistant, verify it locally, and then provide controlled remote access
ESPHome Designer is a browser-based visual editor for building display layouts for ESPHome, OpenEpaperLink, and OpenDisplay projects. This guide focuses first on manually installing its Home Assistant custom component, adding the integration, and confirming that the editor works at the documented /esphome-designer path. We also cover the recommended HACS route and the project's standalone development options so that you can distinguish them from the manual integration workflow. After local verification, we explain how to connect the working Home Assistant HTTP service to a public HTTPS address with Localtonet.
What ESPHome Designer adds to Home Assistant
ESPHome Designer is a visual drag-and-drop editor for smart display layouts. Its supported output targets include ESPHome C++ lambda code or LVGL YAML, OpenEpaperLink Home Assistant service-call data, and OpenDisplay JSON actions. The project can run as a Home Assistant integration or as a standalone web application.
The editor is intended to reduce the amount of display code that must be written manually. It supports browser-based layout design, multiple project pages on a unified stage, Home Assistant entities and MQTT topics as data sources, conditional widget visibility, time-based page scheduling, and round-trip importing of supported configuration formats. The project documentation also describes more than 55 independent widget modules.
Installing the Home Assistant integration does not mean that the editor automatically changes an ESPHome device configuration. The documented workflow is to create a layout, generate the relevant ESPHome snippet, copy or merge that snippet into the actual device YAML, and then compile and flash the device through the normal ESPHome workflow. Saving a layout in the editor preserves the design state, but it does not overwrite the real ESPHome device YAML file.
/esphome-designer path.
Choose the correct installation method
The upstream project documents several ways to use the editor. HACS is the recommended Home Assistant installation method, while copying the custom component is the manual alternative covered in detail here. The npm and Python options are documented as local development servers, not as production deployment instructions.
| Method | Best suited to | Documented access point |
|---|---|---|
| Manual custom component | Home Assistant users who need to install the integration without HACS | The Home Assistant path /esphome-designer |
| HACS custom repository | Home Assistant users who want the upstream recommended installation route | The Home Assistant path /esphome-designer |
| npm development server | Local frontend development and testing | http://localhost:5174 |
| Python HTTP server | Locally serving the packaged frontend for development | http://localhost:8000 |
The ESPHome Designer documentation establishes the /esphome-designer path, but it does not establish a universal Home Assistant hostname or port. Use the same local Home Assistant origin that already works in your environment, then append the documented path. Do not copy a guessed host or port into Home Assistant or Localtonet.
Prerequisites for a manual installation
Begin with a working Home Assistant installation that you can access locally. You must also be able to place files inside the Home Assistant configuration directory and restart Home Assistant. The exact host-side location of that directory depends on how Home Assistant was installed, so this guide does not assume an operating system path.
Download the project files from the official ESPHome Designer repository and locate the directory named custom_components/esphome_designer. Preserve that directory as a complete custom component. Copying unrelated repository files or only selected files from inside the component can leave Home Assistant without the manifest or modules it needs to load the integration.
Manual custom-component installation changes files under the Home Assistant configuration directory. Create an appropriate backup before copying or replacing files. Authentication tokens, Home Assistant credentials, Localtonet device tokens, and private endpoint details must not be placed in screenshots, command history, shared configuration examples, or public issue reports.
How to manually install ESPHome Designer
The following sequence preserves the installation order documented by the project. Complete all four actions before troubleshooting the editor path or configuring remote access.
Download the ESPHome Designer custom component
Obtain the project files and select the complete custom_components/esphome_designer folder. Keep the folder name and its internal structure intact.
Copy the component into the Home Assistant configuration
Place the esphome_designer folder inside Home Assistant's config/custom_components/ directory. The resulting component location should correspond to config/custom_components/esphome_designer, where config represents your actual Home Assistant configuration directory.
Restart Home Assistant
Restart Home Assistant after the files are in place. A browser refresh alone does not make Home Assistant load a newly copied custom component.
Add the ESPHome Designer integration
In Home Assistant, open Settings, select Devices & Services, and add the ESPHome Designer integration. Complete the integration flow presented by Home Assistant.
Verify the integration locally
Do not create a public tunnel until the editor works from a browser on the local network. Open your existing Home Assistant address and append /esphome-designer. For example, if your known local Home Assistant origin is represented as HOME_ASSISTANT_ORIGIN, the path to test is:
HOME_ASSISTANT_ORIGIN/esphome-designer
HOME_ASSISTANT_ORIGIN is a placeholder, not a literal hostname. Replace it with the Home Assistant origin you already use. A successful check should load the ESPHome Designer interface through Home Assistant. Confirm that the page remains usable after a refresh and that you can open the editor without depending on an external connection.
If the integration does not appear in the Add Integration dialog, first verify the directory nesting. A common manual-installation mistake is creating an extra directory level, such as placing the component beneath another repository folder. Then confirm that Home Assistant was fully restarted after the copy. Home Assistant logs can provide the specific loading error if the component was discovered but could not initialize.
Understand where the integration stores data
Inside Home Assistant, saved layouts and editor state are stored in /config/.storage/esphome_designer. Manual edits made in the editor's YAML snippet box are stored as part of the active layout state rather than as a separate ESPHome device YAML file. Uploaded custom hardware profiles are stored under /config/esphomedesigner_custom_profiles/*.yaml.
If you inspect these locations from the host operating system, replace /config with the real Home Assistant configuration directory. The .storage area is managed by Home Assistant, so avoid casual manual edits. Use the editor and Home Assistant workflows to manage the integration's state unless the project documentation explicitly calls for a maintenance action.
Save Layout stores the canvas, settings, and persisted manual YAML override in the active layout. It does not automatically replace an ESPHome device configuration. Review generated output, merge it into the intended device YAML, and compile or flash it through the established ESPHome process.
Optional standalone development checks
The standalone commands are useful when working on the frontend or testing it separately from the Home Assistant integration. They are not required for the manual custom-component installation. Run only the path appropriate to your development goal.
Run the npm development server
From the project directory, the documented npm workflow installs dependencies and starts the development server:
npm install
npm run dev
The evidenced local endpoint for this method is http://localhost:5174. Verify it on the machine running the command before considering any remote connection.
Serve the packaged frontend with Python
The project also documents serving the packaged frontend with Python's HTTP server:
python3 -m http.server 8000
The evidenced endpoint is http://localhost:8000. This is also presented as a local development option. A basic development server should not be treated as a hardened production deployment merely because it can be reached through a tunnel.
Expose the verified service with Localtonet
Once ESPHome Designer works locally, the next step is to connect the underlying HTTP service with Localtonet. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
For the Home Assistant integration, the tunnel target is the local Home Assistant HTTP service, not the path by itself. Configure the local IP address and port that the Localtonet client device can reach. The public address can then carry requests to the /esphome-designer path. For a standalone development server, the evidenced local port is either 5174 or 8000, depending on which documented command you started.
Install and run the Localtonet client
Run our client on the Home Assistant host or on another device that can reach the verified local HTTP service.
Authenticate the client device
Select the device by using its device-specific authentication token. Keep that token private and never place it in tutorial examples or public configuration.
Select an available relay server
Choose an available relay server or region from the current dashboard. Server codes and availability can change, so obtain the value from the product rather than hardcoding one.
Create an HTTP tunnel configuration
Point the HTTP tunnel to the local IP address and port of the service you already verified. For Home Assistant, use its real reachable HTTP target. For a documented standalone check, use the applicable local development-server target.
Start the tunnel and test the public address
Creating a tunnel does not start it. Press Start, then open the assigned public HTTPS address. Append /esphome-designer when accessing the Home Assistant integration.
Stop or delete the tunnel when it is no longer needed
The tunnel is available only while the selected client is connected and the tunnel is running. Stop it after temporary access, or delete it when the configuration is no longer required.
For current dashboard details, consult our Localtonet HTTP tunnel documentation. HTTP process types can provide a random subdomain, a supported custom subdomain, or a custom domain. Exact custom-domain DNS requirements should always be checked against current documentation before making DNS changes.
Confirm that Home Assistant and any related access controls are configured appropriately before starting the tunnel. Use authentication, least privilege, IP restrictions, and other available controls where relevant. Do not expose a development server as though it were a production service, and do not share the public address with users who should not reach the application.
Frequently asked questions
What URL should I use for ESPHome Designer in Home Assistant?
Use your existing Home Assistant origin followed by /esphome-designer. The project documents the path but does not specify a universal Home Assistant hostname or port.
Is manual installation required if I use HACS?
No. HACS and manual copying are separate installation methods. The project recommends adding its repository to HACS, installing ESPHome Designer, restarting Home Assistant, and adding the integration through Settings and Devices & Services.
Does saving a layout update my ESPHome device YAML automatically?
No. Saving preserves the layout and its state in Home Assistant storage. The normal workflow is to copy or merge the generated snippet into the device configuration and then compile or flash through ESPHome.
Can I tunnel only the /esphome-designer path?
The Localtonet HTTP tunnel targets a local IP address and port. For the integration, that target is the reachable Home Assistant HTTP service. The browser then requests the /esphome-designer path through the public address.
Does creating a Localtonet tunnel make it immediately available?
No. After creating the configuration, you must start the tunnel. It remains available only while the selected client device is connected and the tunnel is running.
Are the npm and Python servers production deployment methods?
The project presents those options as local standalone development servers. Their documented endpoints are http://localhost:5174 for npm and http://localhost:8000 for Python. Do not assume that either method provides production hardening.
Connect your verified ESPHome Designer service
After the integration works locally and its access controls have been reviewed, use Localtonet to provide an on-demand public HTTPS address without configuring inbound router port forwarding.
Get Started Free →
