Install ESP-KVM on ESP32-P4: Browser IP-KVM Guide

What ESP-KVM does and why it differs from remote desktop

A normal remote desktop application runs inside the operating system being controlled. It depends on that operating system booting successfully, starting its network stack, and keeping the remote-access software available. It cannot normally help when a machine is waiting at a BIOS prompt, displaying a bootloader error, installing a new operating system, or failing before the remote desktop service starts.

ESP-KVM works outside the target operating system. A supported ESP32-P4 board receives the target computer's video through an HDMI-to-CSI capture board. The ESP-KVM hardware also connects to a USB port on the target and presents keyboard and mouse input. Its browser console is served by the ESP-KVM device itself, so nothing needs to be installed on the computer being managed.

The firmware also supports capabilities such as screenshots, recording to microSD, text-mode screen reading, macros, scheduled runbooks, serial-console access, Wake-on-LAN, and optional power or reset control. Some of these features depend on the selected board, attached storage, extra wiring, or optional hardware. The interface disables unsupported functions rather than implying that every board can provide every feature.

Hardware and prerequisites

Start by choosing an ESP32-P4 board for which ESP-KVM publishes a matching firmware image. A generic image should not be substituted for a board-specific image because pin assignments, network hardware, storage wiring, and USB connections vary between boards. ESP32-P4 chip revision also matters. Revision 3.x silicon uses its own image, and the project reports significantly faster H.264 processing at 1080p on that revision.

The project identifies revision 3.x parts by the ESP32-P4 chip marking and also reports the revision in the boot log. If there is any uncertainty, confirm the exact board model and chip revision before downloading or flashing firmware.

Supported board examples

Documented board choices include the Waveshare ESP32-P4-ETH, Espressif ESP32-P4 Function EV, Waveshare ESP32-P4-NANO, Guition ESP32-P4-M3-Dev, Waveshare ESP32-P4-WIFI6-POE-ETH, Waveshare ESP32-P4-WIFI6, Waveshare ESP32-P4-WIFI6-DEV-KIT, DFRobot FireBeetle 2 ESP32-P4, M5Stack Unit PoE-P4, and Waveshare ESP32-P4-NANO-WIFI6-DB. Additional images exist for other boards, but some combinations are marked untested by the project.

An image being available does not necessarily mean its hardware combination has been physically verified. If the project's current board list labels a model untested, treat it as an experimental choice. For a first installation, a tested board and revision are the safer route.

Capture-board differences

Most documented builds use a separate TC358743 HDMI-to-CSI adapter connected by a ribbon cable. The M5Stack Unit PoE-P4 instead uses its corresponding Add-on Display In hardware. Do not assume that capture adapters or ribbon pinouts are interchangeable.

Know the correct USB OTG port

The USB port used to control the target depends on the ESP32-P4 board. On the Waveshare ESP32-P4-ETH, for example, the project's quick-start guidance identifies the MX1.25 header as the target-facing OTG connection, not the USB-C connector. Connecting the wrong port can leave the web console reachable while keyboard and mouse control remain unavailable.

Flash ESP-KVM firmware

ESP-KVM provides two practical binary installation paths. The easiest path uses the browser flasher in Chrome or Edge. The alternative downloads the merged firmware image for the exact board and writes it with esptool. Choose one path rather than running both.

Option 1: flash from Chrome or Edge

Option 2: flash a merged image with esptool

Use this method when browser serial flashing is unavailable or when a repeatable local firmware file is preferred. Download the merged binary whose filename identifies the ESP-KVM version and exact board. Do not rename a generic or different-board image and assume it will become compatible.

The documented write address is 0x0, the chip argument is esp32p4, and the documented baud rate is 921600:

esptool --chip esp32p4 -b 921600 write-flash 0x0 espkvm-<version>-<board>-merged.bin

Replace the filename placeholder with the actual merged image downloaded for the board. Depending on the installed esptool environment and operating system, serial-port selection may also be necessary. The supplied evidence does not establish one universal serial-port argument or device path, so this guide does not invent one. Use the port shown by the operating system for the connected board.

Building from source

ESP-KVM also documents a source-build workflow based on ESP-IDF 6.1. A source build is appropriate when developing firmware, testing an unreleased change, or modifying a board definition. It is not necessary for a normal installation when a matching merged image exists.

The evidence available for this draft establishes the required ESP-IDF version but does not provide the complete current command sequence, board-selection mechanism, submodule requirements, or generated image paths. Those values can change with the repository. Rather than guessing commands that could build the wrong target, this guide recommends the browser flasher or board-specific merged image for the documented installation workflow.

Connect ESP-KVM to the network and target computer

Once flashing is complete, assemble the functional KVM path. There are three independent links to verify: network access to ESP-KVM, HDMI video from the target, and USB control from ESP-KVM to the target.

Optional front-panel power and reset control requires additional hardware such as optocouplers or relays. Do not connect a motherboard's front-panel header directly based on an assumed pinout. Basic video, keyboard, and mouse testing should be completed before optional control wiring is introduced.

Complete first-boot configuration

Ethernet or already-connected network

From a client on the same trusted network, open:

https://espkvm.local/

The documented initial credentials are username admin and password admin. On the first sign-in, ESP-KVM asks for a new password. Complete that password change immediately and store the new credential securely.

Wi-Fi setup without a network cable

A supported board equipped for Wi-Fi can expose a setup hotspot named in the following pattern:

ESP-KVM-xxxx

Connect a setup device to that hotspot and open:

http://192.168.4.1/

Use the setup interface to complete the device's local network configuration. The hotspot path is a provisioning and recovery mechanism, not a reason to leave the device on an untrusted wireless network.

Trust the device certificate authority where appropriate

ESP-KVM creates a certificate on the device at first boot. Its certificate authority can be downloaded through Settings → Security → Download CA certificate or from the local certificate endpoint:

http://espkvm.local/cert.pem

Install a private device CA only on systems where that trust is intended and administratively acceptable. Trusting a CA changes browser and operating-system trust decisions, so do not install it broadly or on unrelated machines. If the KVM is rebuilt or its certificate state changes, previously trusted certificate material may no longer match.

Enable two-factor sign-in if it fits the deployment

ESP-KVM supports optional codes from an authenticator application. A strong unique password remains necessary, but two-factor sign-in provides an additional barrier when an interactive login path is reachable by more than one administrator or network segment.

Verify the local IP-KVM before considering remote access

Remote tunneling should never be the first diagnostic step. Confirm that the KVM works reliably from the local network, because a tunnel cannot repair incorrect flashing, failed HDMI capture, wrong USB wiring, certificate errors, or an unstable power supply.

Build a local verification matrix

Evaluate controlled remote access with Localtonet

ESP-KVM's own guidance says not to put the device on the public internet. It has login, optional two-factor sign-in, and TLS, but the project states that it has not received an external security review, secure boot and flash encryption are disabled, and update images are not signed. The project recommends keeping the KVM on a trusted network or using its built-in Tailscale or WireGuard support.

That warning must remain the starting point for any Localtonet evaluation. A Localtonet HTTP tunnel can provide a public browser address without inbound router port forwarding, firewall changes, a VPN setup, or a public IP address. However, turning a private KVM interface into a publicly reachable service increases its exposure. It should be considered only after a risk review and only with strong ESP-KVM authentication, limited duration, active monitoring, and compatibility testing.

Required network architecture

The Localtonet client does not run on ESP-KVM itself. It must run on another supported device that can reach the KVM over the trusted LAN. That device establishes an outbound connection to our relay and forwards traffic toward the local ESP-KVM service.

Why the exact target port is not provided here

The verified ESP-KVM quick-start endpoint is https://espkvm.local/, but the project material supplied for this guide does not state a numeric web port. Localtonet HTTP configurations point to a local IP address and port, so that numeric target must be confirmed from the current ESP-KVM network behavior or project documentation before the tunnel is created.

We do not infer a port solely from the https:// scheme. We also do not assume how ESP-KVM certificate validation, hostnames, redirects, WebSockets, H.264 transport, or interactive control sockets will behave through a relayed public origin. Test each required function rather than treating a loaded login page as proof of full compatibility.

Localtonet setup sequence

For the current dashboard workflow and available HTTP options, consult the Localtonet documentation. Exact region choices, client installation details, and available configuration options may change by client version, deployment, or plan.

Compatibility tests that matter for an IP-KVM

A successful sign-in is only the first test. ESP-KVM is an interactive application that may maintain long-lived browser connections for video and controls. Verify all operations needed during an actual outage:

• Load and reload the login page from a network outside the management LAN.
• Confirm password and optional two-factor authentication.
• Start MJPEG video and verify that it remains current rather than accumulating delayed frames.
• Test H.264 separately because ESP-KVM requires HTTPS for that mode.
• Send keyboard, modifier-key, pointer, and paste input.
• Switch target resolutions by entering firmware setup and then booting the operating system.
• Leave the session idle, return to it, and confirm that video and controls recover.
• Test from the actual remote browser types that administrators will use.
• Stop the Localtonet tunnel and verify that the public address no longer provides the intended access path.

Safe operation and maintenance

Keep the management network trusted

Place ESP-KVM on a management network appropriate for hardware administration. Anyone who controls the KVM can potentially interact with firmware settings, boot alternate media, enter recovery environments, and operate the target independently of its normal operating-system permissions.

Use a unique administrator password and enable optional two-factor sign-in where practical. Do not share a single credential through chat history, tickets, or public automation. If access is no longer needed, remove it rather than relying on obscurity.

Treat virtual media as privileged access

Virtual media can be valuable for installing or repairing a system, but it can also change the target's boot process. Store only approved images, verify their provenance, and detach media after use. MicroSD may use FAT32 or exFAT, with exFAT allowing images larger than 4 GB.

Video and storage activity may compete for device resources on some boards. If a large image upload performs poorly, the project's guidance recommends pausing video during the upload.

Approach firmware updates cautiously

ESP-KVM supports browser-delivered updates, two firmware slots, and rollback when a new image fails to start. Rollback improves recovery from a failed boot, but it does not replace change control. Record the working version, schedule updates when local recovery is possible, and verify video, input, login, and networking after each change.

The project warns that update images are not signed and that secure boot and flash encryption are disabled. Account for those limitations when deciding where the device can be deployed and who can physically or logically administer it.

Stop temporary tunnels

With Localtonet, a configured tunnel is not active merely because it exists. It must be started, and it can later be stopped or deleted. For temporary maintenance, stop the tunnel immediately after the session and delete configurations that are not expected to be reused.

Keep the Localtonet device token private. A token identifies the client device that runs the tunnel and must not be included in screenshots, code examples, logs shared publicly, or documentation.

Troubleshooting ESP-KVM installation and access

The browser flasher cannot see the board

Confirm that Chrome or Edge is being used, the USB cable supports data, and the board is connected through its documented programming interface. Close applications that may already hold the serial port. If several serial devices are attached, disconnect unrelated hardware and retry.

esptool cannot start or maintain the flash

Verify that the selected image is a merged image for the exact board, the chip is specified as esp32p4, and the write offset is 0x0. A failing high-speed serial link may involve the cable, USB adapter, power, host port, or driver. The documented command uses 921600, but this guide does not prescribe undocumented recovery flags or alternate rates.

The board starts, but espkvm.local does not resolve

The .local name depends on local name discovery. Confirm that the client and KVM are on the same appropriate network segment and that multicast discovery is not blocked. Check the network's device or DHCP list for the board's assigned address. On a Wi-Fi-capable board with no cable, look for the ESP-KVM-xxxx hotspot and use http://192.168.4.1/ for setup.

The browser reports a certificate warning

ESP-KVM creates a device certificate at first boot. Confirm that the address is genuinely the intended KVM before accepting or changing any trust decision. For managed trust, download the CA through the Security settings or the local /cert.pem endpoint and install it only where authorized.

The console loads, but there is no video

Check that the target is producing HDMI output, that the cable reaches the capture adapter's input, and that the CSI ribbon is fully seated in the correct orientation. Confirm the capture board is supported. Test a common target resolution and inspect behavior during startup, when firmware output should normally appear.

Video works, but keyboard and mouse do not

This usually separates the capture path from the USB control path. Verify that the target is connected to the ESP-KVM board's correct USB OTG interface. Do not assume the flashing or power connector is also the target-facing OTG port. Try another known data-capable cable and confirm that the target supplies or detects USB as expected.

H.264 does not work

ESP-KVM requires HTTPS for H.264. First verify the local HTTPS endpoint and certificate behavior. If local H.264 works but remote H.264 fails, treat that as tunnel compatibility evidence. Do not assume the tunnel is fully compatible just because MJPEG or the login page works.

The Localtonet client cannot reach ESP-KVM

Test the local ESP-KVM endpoint directly from the machine running the Localtonet client. Confirm the LAN address, numeric service port, routing, and local firewall policy. The Localtonet client must be on a device that can reach the target service. A working console on a different laptop does not prove that the tunnel client has the same network path.

The public page loads, but controls or video disconnect

Test MJPEG and H.264 independently, inspect whether the problem follows one browser, and check whether local access remains stable at the same time. Interactive video and control paths may behave differently from ordinary page requests. If required sockets, certificate behavior, or browser-origin rules are incompatible, stop the tunnel instead of weakening security controls.

The tunnel appears configured but is unreachable

Confirm that the selected Localtonet client device is connected and that the tunnel has actually been started. Creating it does not start it. Also verify that the local service remains reachable from the client device and that the configured IP address and numeric port are correct.

Frequently asked questions