Host Platform

The host platform allows ESPHome configurations to be compiled and run on a desktop computer. This is known to work on MacOS and Linux. On Windows WSL (Windows Subsystem for Linux) can be used to create a Linux environment that will run ESPHome.

The only configuration required is to optionally set a dummy MAC address that will be used to identify the configuration to Home Assistant (the native MAC address is not readily available.)

ℹ️ Note
HA will not automatically discover an ESPHome instance running on host using mDNS, and you will need to add it explicitly using the IP address of your host computer. If HA cannot establish a connection when adding the device manually, the firewall settings of the local host computer may be the cause. The ESPHome API port (6053) must be allowed through the firewall of your host to accept connections. See Native API Component for details.

Many components, especially those interfacing to actual hardware, will not be available when using host. Do not configure wifi or ethernet - network will automatically be available using the host computer. Check out the See Also section at the bottom of this page for components working specifically with host platform.

# Example configuration entry
host:
  mac_address: "06:35:69:ab:f6:79"

Configuration variables

mac_address (Optional, MAC address): A dummy MAC address to use when communicating with HA.

Lambda calls

The execute_shell_command function can be used in a lambda to run linux shell commands on the host operating system, and retrieve the Standard Output, Standard Error and Exit Code of the result.

⚠️ Warning
This function provides full, unsandboxed access to the host operating system. Commands execute with the same privileges as the ESPHome process - if running as root, commands have root access. There is no input validation, command filtering, or security sandboxing. Only use this on systems you fully control and trust, and never expose the API to untrusted networks. Malicious or accidental misuse could result in data loss, system compromise, or other serious consequences.

You can set a shell to run the commands in, and you can specify custom environment variables too.

# Example configuration entry
button:
  - platform: template
    name: "Kernel version (sh)" # get shell type and kernel version number
    on_press:
      - lambda: |-
          auto result = esphome::host::execute_shell_command("ps -p $$ -o comm=; uname -r");
          id(last_exit_code).publish_state(result.exit_code);
          id(last_stdout).publish_state(result.stdout_output);
          id(last_stderr).publish_state(result.stderr_output);

  - platform: template
    name: "Envvars test (bash)" # get shell type and see if environment variable set works
    on_press:
      - lambda: |-
          esphome::host::ShellCommandOptions opts;
          opts.shell = "/bin/bash";
          opts.environment = {
            {"FOO", "BAR"},
          };
          auto result = esphome::host::execute_shell_command("ps -p $$ -o comm=; printf 'FOO=\"%s\"\n' \"${FOO-}\"", opts);
          id(last_exit_code).publish_state(result.exit_code);
          id(last_stdout).publish_state(result.stdout_output);
          id(last_stderr).publish_state(result.stderr_output);

  - platform: template
    name: "Run Command" # get first 255 characters of the output of any command typed in the text component
    on_press:
      - lambda: |-
          auto result = esphome::host::execute_shell_command(id(arbitrary_command).state.c_str());
          id(last_exit_code).publish_state(result.exit_code);
          id(last_stdout).publish_state(result.stdout_output.substr(0, 254));
          id(last_stderr).publish_state(result.stderr_output);

text:
  - platform: template
    name: "Command"
    initial_value: "cat /definitely-does-not-exist"
    id: arbitrary_command
    optimistic: true
    min_length: 0
    max_length: 100
    mode: text

text_sensor:
  - platform: template
    id: last_stdout
    name: "Last Command Stdout"
  - platform: template
    id: last_stderr
    name: "Last Command Stderr"

sensor:
  - platform: template
    id: last_exit_code
    name: "Last Command Exit Code"

Check out the Cookbook for examples on how to create a couple of controls and sensors for a Linux host.

ℹ️ Note
Commands will be run with the same privileges as the ESPHome binary. Take extra care for the commands to finish! Running a command that never exits will lock up the ESPHome binary too. Put the commands in double quotes. If the command itself needs to contain double quote characters, escape them with \.

⚠️ Warning
You should NOT run any commands using this facility that contain data accepted from any outside input (webserver, HA text sensors etc.) unless that data has been well sanitised, since this risks a command injection attack.

Build and run

The esphome run yourfile.yaml command will compile and automatically run the build file on the host platform.

The binary path will be printed in the terminal, you can copy it to your favourite location on the host file system and run it from there directly, without having to invoke ESPHome every time.