Add --socket option to listen on a UNIX socket

[vexofp]

What does this implement/fix?

Add a command line option (--socket) that makes the primary web server listen on a specified UNIX socket path (instead of TCP). This restores a feature that was previously available in the legacy dashboard.

Related issue or feature (if applicable):

• fixes https://github.com/orgs/esphome/discussions/3754

Types of changes

• Bugfix (non-breaking change which fixes an issue) — bugfix
• New feature (non-breaking change which adds functionality) — new-feature
• Enhancement to an existing feature — enhancement
• Breaking change (fix or feature that would cause existing functionality to not work as expected) — breaking-change
• Refactor (no behaviour change) — refactor
• Documentation only — docs
• Maintenance / chore — maintenance
• CI / workflow change — ci
• Dependencies bump — dependencies

Frontend coordination

• No frontend change needed
• Companion frontend PR: esphome/device-builder-frontend#

Checklist

• The code change is tested and works locally.
• Pre-commit hooks pass (ruff, codespell, yaml/json/python checks).
• Tests have been added or updated under tests/ where applicable.
• components.index.json / definitions/components/*.json have not been hand-edited (regenerate via script/sync_components.py if a sync is needed).
• Architecture-level changes are reflected in docs/ARCHITECTURE.md and/or docs/API.md.

[vexofp]

The option name (--socket) and behavior (overriding --host/--port) were chosen to mirror that of the legacy dashboard. The host/port options do still affect the mDNS advertisement, which seems useful if you point them at where a reverse proxy ultimately listens.

The current changes do not affect the HA ingress or remote build sites, since UNIX socket listening is mainly used with reverse proxies and seems less useful/applicable for those. If requested in the future, --ingress-socket/--remote-build-socket options could extend the pattern to those sites.

I did not find any existing tests that seemed related to the socket binding options, so I held off adding anything for now. Happy to add some if I can get a bit of direction as to the preferred location/approach.

[bdraco]

Definitely needs some tests for this

[bdraco]

@esphbot review

[esphbot]

@vexofp: The option name (--socket) and behavior (overriding --host/--port) were chosen to mirror that ...

Direction on tests: use tests/test_ha_addon_failsafe.py. Mirror test_non_ha_addon_binds_public_site_normally. Patch device_builder.web.run_app with a fake_run_app. Assert path == <socket>, host == [], and resolve_bind_host not called. Cover both branches — standard and the add-on serve_public_unauthenticated path. Also document --socket in README/ARCHITECTURE; the ticked docs box has no diff behind it.

[esphbot]

@bdraco: Definitely needs some tests for this

Agreed. Location: tests/test_ha_addon_failsafe.py. Reuse the fake_run_app capture pattern. Assert path forwarded, host empty, resolve_bind_host skipped. One case per run() branch.

[esphbot]

Previous review — superseded by a newer review below.

[esphbot]

Blocking issues found.

• No test coverage for the --socket path (maintainer-requested)
• New --socket flag is undocumented, but the docs checkbox is ticked

[codspeed-hq]

Merging this PR will not alter performance

✅ 27 untouched benchmarks

---

_{Comparing vexofp:unix-socket (06862af) with main (9bedc3d)}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.58%. Comparing base (d1fd04c) to head (06862af).
⚠️ Report is 60 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1862      +/-   ##
==========================================
+ Coverage   99.56%   99.58%   +0.01%     
==========================================
  Files         234      239       +5     
  Lines       18982    19399     +417     
==========================================
+ Hits        18899    19318     +419     
+ Misses         83       81       -2     

Flag	Coverage Δ
py3.12	99.55% <100.00%> (+0.02%)	⬆️
py3.14	99.58% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
esphome_device_builder/__main__.py	95.38% <ø> (+1.11%)	⬆️
...home_device_builder/controllers/config/settings.py	100.00% <100.00%> (ø)
esphome_device_builder/device_builder.py	98.03% <100.00%> (+0.01%)	⬆️

... and 53 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vexofp]

Added additional documentation and UNIX socket case coverage to the relevant test_*_binds_public_* tests.

Did not try to tackle messing with the socket file permissions. (Which is a divergence from the legacy dashboard.) For one, it is poorly-supported / rather cumbersome under aiohttp (see aio-libs/aiohttp#4155). Also, the legacy behavior of making the socket world-writable was problematic, since that undermines one of the key security advantages of UNIX sockets and any work-around that later restricts the socket file suffers from a vulnerable race window. There are other ways of safely adding access for socket files (e.g. default ACLs). If there are requests for something like a --socket-mode option in the future, that seems like it could fit its own PR.

[bdraco]

If you want to do an aiohttp PR, I can take a look

[esphbot]

@vexofp: Added additional documentation and UNIX socket case coverage to the relevant test_*_binds_public_*...

Agreed on skipping socket perms. World-writable defeats the socket boundary; post-bind chmod has a race window. Default ACLs or same-uid proxy are the safe paths. Fits a future --socket-mode PR.

One nit on the added tests: assert captured["host"] == [] if unix_socket else ["0.0.0.0"] binds == tighter than the ternary. The None branch asserts a truthy literal, so the TCP host check never runs. Parenthesize: == ([] if unix_socket else ["0.0.0.0"]).

[esphbot]

Previous review — superseded by a newer review below.

[esphbot]

Blocking issues found.

• Operator precedence makes the TCP-path host assertion vacuous

[esphbot]

@bdraco: If you want to do an aiohttp PR, I can take a look

One aiohttp-adjacent gap here. UnixSite.start() calls create_unix_server without passing cleanup_socket, relying on the default. On Python 3.13+ asyncio removes a stale socket before bind and unlinks on clean close, so modern runtimes are covered. On the 3.12 floor neither exists — stale file, then EADDRINUSE on restart. An aiohttp-level knob for socket mode (or explicit stale-unlink) would help pre-3.13, else docs can note the floor.

[esphbot]

PR Review — Add --socket option to listen on a UNIX socket

Clean, correctly-scoped feature; the prior operator-precedence blocker is now fixed and nothing else blocks merge.

Specific strengths:

• The subtle bind logic is right and verified: host=[] (not None) suppresses TCP binding in aiohttp's _run_app while path= adds the UnixSite, so no unintended TCP port is opened, and --host/--port stay live for mDNS advertisement.

• The front-door banner %s%s%s formatting renders the socket path alone vs host:port correctly for both branches.

• The prior blocker is resolved — all three parametrized asserts now use == ([] if unix_socket else ["0.0.0.0"]) with the parentheses, restoring the real host check on the TCP path.

• Docs section added covering auth/Origin gates staying active and the mDNS/reverse-proxy precedence.

• Non-blocking: stale-socket cleanup is handled by asyncio on Python ≥3.13 but likely not on the declared 3.12 floor (unverified) — worth confirming or documenting.

---

---

Checklist

• Bind logic correct (no unintended TCP port; host=[] suppresses TCP, path= adds UnixSite)
• Prior operator-precedence blocker resolved (parenthesized ternary)
• Front-door banner reports socket vs host:port correctly
• Auth / Origin gates unchanged; no new security hole (default umask restricts socket to owner)
• Stale-socket / cleanup handled across supported Python floor
• Docs updated for CLI flag and trust boundary

---

Automated review by Kōan (Claude) HEAD=06862af 5 min 27s

[esphbot]

No blocking issues found.

[bdraco]

Please update THREAT_MODEL.md to explain the default permissions are not a bug and not something we defend