Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesInstall ESPHome on a VPS by running the official ghcr.io/esphome/esphome image with a persistent /config volume and dashboard port 6052 published. Use ordinary port mapping when each device has a reachable fixed address; use Docker host networking on a Linux VPS when you need mDNS discovery and .local names. A VPS normally cannot perform the first USB flash because the ESP board is not physically attached to it, so flash from a USB-connected computer and use the VPS for dashboard management and reachable over-the-air updates.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
What you need before installing
- A VPS running Docker Engine and, if you plan to use host networking, a Linux host. Docker host networking is Linux-specific in the ESPHome guidance.
- A directory on the VPS that will persist ESPHome YAML files. The container stores its dashboard configuration under
/config; without a bind mount, recreating the container can remove your working files. - Network access to the VPS on TCP port
6052. Allow that port in both your VPS provider firewall and the operating system firewall, or keep it private and connect through an SSH tunnel. - An ESP board and USB cable for initial flashing. The board must be connected to the computer that performs the flash; a remote VPS generally has no access to your local USB serial device.
The image has three documented channels: stable (the default when no tag is specified), beta, and dev. Use the untagged image for a normal installation unless you have a specific reason to test another channel.
As an Amazon Associate I earn from qualifying purchases.
Choose the Docker network mode first
The network choice determines whether the dashboard can discover devices automatically. It does not change where your YAML files are stored.
| Mode | Run setting | Discovery behavior | Best fit |
|---|---|---|---|
| Published port | -p 6052:6052 |
Dashboard is reachable on port 6052, but devices need a fixed address in their YAML, such as use_address or manual_ip. |
A VPS that reaches devices through routed IP addresses, a VPN, or another network path. |
| Host networking | --net=host |
On Linux, the container can use mDNS discovery, resolve .local names, and report online status through the host network. |
A Linux machine on the same Layer-2 network as the ESP devices. |
Host networking is not a magic bridge between separate networks. If your VPS is in a data center and the ESP devices are at home, mDNS packets normally do not cross that boundary. You still need routed connectivity, a VPN, or fixed addresses that the VPS can reach.
#1 Best Overall
- 2.4GHz Dual Mode WiFi + Bluetooth Development Board
- Support LWIP protocol, Freertos
- SupportThree Modes: AP, STA, and AP+STA
- Ultra-Low power consumption, Compatible with Arduino IDE
- ESP32 is a safe, reliable, and scalable to a variety of applications
Install with docker run
1. Create and enter a persistent configuration directory
- Create a directory owned by the account that will manage ESPHome, then enter it. For example:
mkdir -p ~/esphome/config cd ~/esphome/config - Keep your device YAML files in this directory. The bind mount in the next command maps it to
/configinside the container.
2. Start the dashboard with published port mapping
This is the portable option and works when the VPS can reach devices by IP:
docker run --name esphome --restart unless-stopped
-p 6052:6052
-v "${PWD}":/config
-it ghcr.io/esphome/esphomeWith no subcommand, the image starts the ESPHome dashboard. The dashboard listens on port 6052 by default. The left-hand side of -p 6052:6052 is the VPS port; the right-hand side is the container port.
If you want the container in the background, add -d and omit the interactive flags:
docker run -d --name esphome --restart unless-stopped
-p 6052:6052
-v "${PWD}":/config
ghcr.io/esphome/esphome3. Open the dashboard
Visit http://VPS_ADDRESS:6052, replacing VPS_ADDRESS with the server’s reachable address. If the page does not load, check the container and listening port:
docker ps
ss -ltn | grep 6052Then verify that TCP 6052 is allowed by the VPS firewall. On systems using UFW, the corresponding rule is:
Rank #2
- Dual-Core Performance Up to 240 MHz: Run sensor processing, wireless communication, automation logic and connected-device tasks on a 32-bit dual-core ESP32 platform designed for responsive embedded and IoT projects
- Built-in Wi-Fi and Bluetooth 4.2: Connect to 2.4 GHz Wi-Fi networks or use Bluetooth Classic and BLE for wireless sensors, smart devices, remote controls, home automation and other connected projects
- Flexible Power-Saving Modes: ESP32 power-management features support dynamic clock scaling and low-power operating modes, helping developers reduce energy use in compatible sensing, monitoring and connected-device applications, suitable for battery-powered Internet of Things (IoT) devices.
- USB-C Programming with CP2102: Connect through USB-C for power, sketch uploads and serial monitoring, while GPIO, UART, SPI and I2C interfaces support sensors, displays, motor drivers and other modules (USB-C cable not included)
- Over-the-Air Update Support: Configure OTA functionality through a compatible ESP-32 software framework to update deployed firmware over Wi-Fi without reconnecting the board by USB for every revision
sudo ufw allow 6052/tcpApply an equivalent rule in your hosting provider’s network firewall. If the dashboard is only for you, a safer arrangement is to bind it to the VPS loopback interface and use an SSH tunnel instead of exposing it publicly:
docker run -d --name esphome --restart unless-stopped
-p 127.0.0.1:6052:6052
-v "${PWD}":/config
ghcr.io/esphome/esphomessh -N -L 6052:127.0.0.1:6052 user@VPS_ADDRESSWith the tunnel running, open http://127.0.0.1:6052 on your own computer. The dashboard port is then not directly reachable from the internet.
Use host networking for mDNS on a Linux VPS
When the Docker host is Linux and is on the same network as the ESP devices, start the image with host networking:
docker run -d --name esphome --restart unless-stopped
--net=host
-v "${PWD}":/config
ghcr.io/esphome/esphomeIn host mode, the container shares the host’s network stack, so do not add -p 6052:6052; the dashboard still uses port 6052 on the host. Open http://HOST_ADDRESS:6052 and make sure the host firewall allows that port.
Host mode helps with mDNS discovery, .local resolution, and online status only when the host can actually see the devices’ network broadcasts. A geographically remote VPS usually cannot, even though the container itself is configured correctly. For a remote installation, use a network route or VPN and put a reachable fixed address in each device configuration.
Rank #3
- Powerful ESP-32 Board: Unlock the world of Internet of Things (IoT) and advanced electronics with the heart of this kit: the ESP-32 board. It features a powerful dual-core processor, integrated Wi-Fi and Bluetooth 4.2, making it perfect for building connected, smart devices that communicate with your phone or the cloud. It's fully compatible with the Arduino IDE for easy programming.
- Super Starter Kit: This kit contains over 35 different modules and electronic components, including sensors, displays, motors, and input devices. From LEDs and buttons to an OLED screen, servo motor, and keypad, you have everything needed to explore a vast range of projects in one box.
- Step by Step Online Tutorial: Jump right in with our detailed, beginner-friendly tutorial. Access 30+ projects with complete code, clear circuit diagrams, and step-by-step instructions. Learn the fundamentals of electronics, coding, and how to utilize the ESP-32's unique capabilities without any prior experience.
- Hands-on Learning for All Skill Levels: Perfect for students, makers, engineers, and hobbyists. Start with basic circuits and coding, then progress to intermediate and advanced IoT applications. Build practical projects like weather stations, smart home controllers, remote-controlled devices, and interactive gadgets. The skills you learn are the foundation for real-world innovation.
- Quality & Great Support: Elegoo is committed to quality. We provide a clear, detailed tutorial guide, refined code, and a well-organized component kit. All modules are carefully selected for reliability and ease of use. Our dedicated technical support team and active online community are ready to help you succeed in your learning journey.
Run ESPHome with Docker Compose
Compose service using host networking
The official Compose pattern uses host networking, a persistent configuration volume, and privileged mode:
services:
esphome:
image: ghcr.io/esphome/esphome
container_name: esphome
network_mode: host
volumes:
- ./config:/config
privileged: true
restart: unless-stoppedSave this as compose.yaml in a directory containing a config subdirectory, then run:
mkdir -p config
docker compose up -dOpen port 6052 on the Linux host. The privileged setting is useful for hardware access, but it grants broad device permissions; on a VPS that will never have a USB board attached, remove it if your setup does not require it.
Compose service using ordinary port publishing
If the VPS is not on the devices’ local network, published-port mode is usually clearer:
Recommended Free Tools
services:
esphome:
image: ghcr.io/esphome/esphome
container_name: esphome
ports:
- "6052:6052"
volumes:
- ./config:/config
restart: unless-stoppedStart it with docker compose up -d. This mode does not provide mDNS across a remote network, so configure fixed device addresses and confirm that routing permits the VPS to reach them.
Rank #4
- 2.4GHz Dual Mode WiFi + Bluetooth Development Board
- Support LWIP protocol, Freertos;ESP32 is a safe, reliable, and scalable to a variety of applications
- SupportThree Modes: AP, STA, and AP+STA
- Ultra-Low power consumption, Compatible with Arduino IDE
- 1PCS 30Pin ESP32 Development Board 2.4GHz WiFi Dual Cores Microcontroller Integrated with Antenna RF Low Noise Amplifiers Filters
Make devices reachable without mDNS
When discovery cannot cross the VPS boundary, set a stable address for each device and reference it in the device YAML. ESPHome supports an explicit use_address value; the networking documentation also describes a manual_ip configuration.
wifi:
ssid: "MyWiFi"
password: "replace-with-your-network-password"
use_address: 192.0.2.50The address must be one the VPS can route to. A private home-LAN address is not automatically reachable from a public VPS. If you change the device’s address, update the YAML and ensure the route, VPN, or firewall policy reflects the new location.
Flash an ESP board when the VPS has no USB port
The first installation on a board normally requires a USB serial connection. A VPS cannot use a USB port that is sitting beside you unless you have deliberately arranged USB-over-network hardware, so perform the initial flash on a local computer.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Local USB workflow
- Install or run the same ESPHome image on the USB-connected computer, or use the dashboard and CLI already installed there.
- Connect the board and identify its serial device, such as
/dev/ttyUSB0on Linux. - Pass that device into a temporary container and run the device YAML. On a Linux computer, the Docker form is:
docker run --rm -it --privileged
--device=/dev/ttyUSB0
-v "${PWD}":/config
ghcr.io/esphome/esphome run living-room.yamlReplace living-room.yaml with the filename in your configuration directory. The --privileged and --device options are for the local machine that has the board attached; they do not make a remote VPS discover a USB device that is not present there.
After the first flash
Once Wi-Fi and the ESPHome firmware are configured, later updates can be sent over the network only if the VPS has a route to the device. A remote dashboard can compile configurations while the update path remains blocked by private addressing, firewall rules, or missing VPN routes. Fix connectivity before treating an OTA failure as a Docker problem.
Best Value
- 2.4GHz Dual Mode WiFi + Bluetooth Development Board
- Ultra-Low power consumption, works perfectly with the Arduino IDE
- Support LWIP protocol, Freertos
- SupportThree Modes: AP, STA, and AP+STA
- ESP32 is a safe, reliable, and scalable to a variety of applications
Dashboard authentication and version-sensitive settings
ESPHome documentation has used different environment-variable names for dashboard authentication: one installation page shows ESPHOME_USERNAME and ESPHOME_PASSWORD, while a command-line getting-started page shows USERNAME and PASSWORD. Do not assume that one spelling works for every image or documentation version. Check the current ESPHome instructions for the image tag you are deploying before adding credentials to Compose or docker run.
Regardless of the variable names, avoid placing a dashboard with no access control on a publicly reachable address. Prefer a private firewall rule, an SSH tunnel, or a VPN, and treat the YAML directory as sensitive because it can contain Wi-Fi credentials and device settings.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Choose and update the image tag
| Tag | Meaning | Use when |
|---|---|---|
| No tag (default) | Stable channel. | Normal production use. |
beta |
Beta channel. | You need a feature or fix not yet in stable and accept additional change risk. |
dev |
Development channel. | Testing unreleased changes, not a conservative production dashboard. |
Pin a channel explicitly if you need repeatable behavior, for example ghcr.io/esphome/esphome:beta. To update an existing Compose deployment, pull the selected image and recreate the service:
docker compose pull
docker compose up -dFor a container started with docker run, stop and remove the old container, pull the image, and run the same command again. Your YAML files remain because they are in the host-mounted /config directory.
Common failures and precise fixes
The browser reports “connection refused”
- Run
docker psand inspect logs withdocker logs esphome. - Confirm the dashboard is listening on 6052 and that your URL uses the VPS address, not a container-only address.
- Check both the VPS operating-system firewall and the provider firewall.
- If you intentionally bound
127.0.0.1:6052, connect through the SSH tunnel rather than the VPS public address.
The dashboard opens, but devices are offline
- In published-port mode, add
use_addressor an appropriatemanual_ipconfiguration to each device YAML. - Verify that the VPS has a route to the device subnet and that the device accepts the required traffic.
- Do not expect mDNS names to work across an unrelated data-center and home network.
mDNS works on a local computer but not on the VPS
- Use
--net=hoston a Linux Docker host and ensure the host itself is on the same local network. - Remember that host networking is Linux-only in the ESPHome guidance and cannot overcome missing routing between sites.
USB flashing fails with a missing serial device
- Perform the flash on the machine physically connected to the board.
- On Linux, pass the actual device path, such as
/dev/ttyUSB0, with--deviceand use the required privileges. - Docker on macOS cannot access host USB devices, so use a suitable local flashing workflow rather than trying to pass a macOS host port into a remote-style container.
Configuration vanishes after recreation
Check the volume mount. The host directory must be mounted to exactly /config; inspect it with docker inspect esphome. Keep backups of the host directory, not just the container.
Host networking behaves differently on Docker Desktop
Docker’s documentation has cited different minimum Docker Desktop versions for host networking: one page says 4.34 and later after enabling it under Settings → Resources → Network, while an FAQ says 4.29 and later. Treat those figures as version-dependent, enable the feature only if your installed release documents it, and use ordinary port mapping when in doubt. A Linux VPS avoids this Docker Desktop-specific ambiguity.
Quick Recap
A repeatable VPS deployment checklist
- Install Docker and create a persistent
configdirectory. - Choose published port mode for routed remote devices, or host mode for a Linux host on the devices’ local network.
- Run
ghcr.io/esphome/esphomewith/configmounted and dashboard port 6052 reachable. - Allow TCP 6052 only where needed, preferably through a private firewall rule, SSH tunnel, or VPN.
- Open the dashboard and create or import device YAML files.
- Flash each new board from a computer with USB access.
- Set fixed device addresses when mDNS is unavailable, then test an OTA update from the VPS.
- Back up the host configuration directory before changing image channels or recreating containers.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
