[Custom Integration] Windmill.dev for Home Assistant – run and monitor scripts and flows

Share your Projects!
,
1

[Custom Integration] Windmill.dev for Home Assistant – run and monitor scripts and flows

I have released a new custom integration that connects Home Assistant to Windmill.

Windmill is an open-source workflow and script automation platform. This integration lets Home Assistant monitor a Windmill instance and run explicitly selected scripts and flows.

The integration supports both self-hosted Windmill installations and Windmill Cloud.

What it can do

Run scripts and flows

Selected Windmill scripts and flows can be started using the windmill.run action.

Arguments are validated against the runnable’s input schema before the request is sent to Windmill.

Parameterless scripts and flows can optionally be exposed as Home Assistant button entities.

Monitor jobs

The integration provides entities for:

  • running jobs
  • queued jobs
  • last successful run
  • last failed run
  • instance and database status
  • active workers
  • worker groups and version drift
  • available Windmill updates on self-hosted installations

Selected scripts and flows can also be exposed as individual Home Assistant devices showing:

  • last run
  • last status
  • last duration
  • next scheduled run
  • whether the runnable is currently running

Use Windmill results in automations

A run event entity emits:

  • success
  • failure
  • canceled

The event includes attributes such as the job ID, script or flow path, duration and whether Home Assistant started the job.

Example:

triggers:
  - trigger: state
    entity_id: event.example_workspace_run
    attribute: event_type
    to: failure

conditions:
  - condition: template
    value_template: >
      {{ trigger.to_state.attributes.path ==
         'u/example/daily_cleanup' }}

actions:
  - action: notify.notify
    data:
      message: >
        Windmill job
        {{ trigger.to_state.attributes.job_id }}
        failed.

Security model

The integration deliberately does not import or expose an entire Windmill workspace.

Only scripts and flows explicitly selected in the integration options can be executed from Home Assistant, with a maximum of 25 selections per configuration entry.

Tokens are sent only in the authorization header and are excluded from logs, entity states and downloaded diagnostics.

Missing permissions disable only the affected feature instead of preventing the complete integration from loading.

Installation

The integration can currently be installed through HACS as a custom repository.

  1. Open HACS.
  2. Go to Integrations.
  3. Open the menu and select Custom repositories.
  4. Add:
https://github.com/dprinz/ha-windmill-dev
  1. Select the Integration category.
  2. Search for Windmill and install it.
  3. Restart Home Assistant.
  4. Add the Windmill integration under Settings → Devices & services.

Repository:

https://github.com/dprinz/ha-windmill-dev

Current status

The current version is 0.3.0.

It has been tested with:

  • self-hosted Windmill Community Edition
  • Windmill Cloud
  • normal and restricted user tokens
  • script and flow execution
  • job cancellation
  • run observation
  • Home Assistant restart and reload scenarios

The project currently has more than 400 automated tests with over 95% branch coverage. HACS validation, hassfest, linting, formatting and strict type checking run in CI.

The integration is considered a public beta because the number of external installations is still small.

Feedback wanted

I would particularly appreciate feedback from users with:

  • different Windmill versions
  • Windmill Enterprise
  • larger or busier workspaces
  • restricted tokens
  • multiple worker groups
  • Windmill Cloud workspaces
  • scripts or flows with more complex input schemas

Please report bugs and feature requests through GitHub Issues. General questions and experiences are also welcome in this thread.