Home Assistant
Running Home Assistant Core and frontend development servers through dot, pitchfork and Herdr.
I work on Home Assistant Core and the frontend most days. dot homeassistant (dot ha) sets up each repository, then runs its dev server as a pitchfork daemon so it gets a stable HTTPS URL from pitchfork’s proxy. Under Herdr, each command opens its own tab in the [HA] Core or [HA] Frontend workspace.
The short hacdev, hafdev* and hadev* functions in .zshrc just call dot ha. Repository paths, workspaces, daemon names, URLs and serve targets live in the private ~/.config/dot/homeassistant.yml, and the pitchfork config lives in the private overlay too, so it is copied below with real URLs replaced.
Commands
| Command | Alias |
|---|---|
dot homeassistant |
dot ha |
dot homeassistant core |
dot ha c |
dot homeassistant frontend |
dot ha f |
| Case | Command | Shortcut |
|---|---|---|
| What is running, and where | dot ha status [target...] |
hadevstatus, hacdevstatus, hafdevstatus, hafdevservestatus, hafdevsuitesstatus |
| Logs | dot ha logs <target> [--follow] [--lines <n>] |
hacdevlogs, hafdevlogs, hafdevservelogs, hafdevdesignlogs, hafdevdemologs, hafdeve2eapplogs |
| Core with the local frontend build | dot ha core dev [--background] |
hacdev, hacdevbg |
Core, rebased onto upstream/dev first |
dot ha core dev --latest [--background] |
hacdevlatest, hacdevlatestbg |
| Core setup (Git, venv, bootstrap) | dot ha core setup [--latest] |
Run by hacdev* |
| Frontend watch build alone | dot ha frontend dev [--background] [--attach] |
hafdev, hafdevbg |
| Frontend against another Core | dot ha frontend serve [<target or URL>] [--background] |
hafdevserve |
| Frontend against prod | dot ha frontend serve prod [--background] |
hafdevserveprod, hafdevserveprodbg |
| Frontend through Home Assistant Link | dot ha frontend serve link [--background] |
hafdevserveprodnc, hafdevserveprodncbg |
| Gallery | dot ha frontend gallery [--background] |
hafdevdesign, hafdevdesignbg |
| Demo | dot ha frontend demo [--background] |
hafdevdemo, hafdevdemobg |
| E2E test app | dot ha frontend e2e [--background] |
hafdeve2eapp, hafdeve2eappbg |
| Production build | dot ha frontend build |
hafbuild |
| E2E tests | dot ha frontend test e2e [app|demo|gallery] |
None |
| Core and frontend in Herdr tabs | dot ha dev [--background] |
hadev, hadevbg |
| Stop servers (all by default) | dot ha stop [target...] |
hadevstop, hacdevstop, hafdevstop, hafdevservestop, hafdevdesignstop, hafdevdemostop, hafdeve2eappstop, hafdevsuitesstop |
| Target | Daemon | URL |
|---|---|---|
core |
ha-core/dev |
https://dev.ha-core.localhost |
build |
ha-frontend/build |
Through Core’s URL |
serve |
ha-frontend/serve |
https://serve.ha-frontend.localhost |
prod |
ha-core/prod |
https://prod.ha-core.localhost |
gallery, demo, e2e |
The frontend’s own background mode | Printed when started |
Port 443 already reaches pitchfork’s proxy (listening on 8443), so the URLs need no port. The proxy builds each hostname from the daemon name and namespace. Its auto-start is off, so a stopped daemon’s URL shows pitchfork’s “No daemon found” page rather than starting it; only the commands start daemons.
How the commands behave
- Interactive runs go through
dot status run, which pins a header with the state, URL and elapsed time, and keeps the terminal title in step. - Each runs its setup first:
dot ha core setupfor Core (Git, virtual environment,script/bootstrap),script/bootstrapfor the frontend. - If the daemon is already running, it asks before restarting it.
dot ha dev’s Frontend tab follows a running build instead. --backgroundstarts the daemon and returns once it’s ready; otherwise it follows the logs, and Ctrl+C stops it.- Every
dot ha frontendcommand takes the frontend’s build lock, so it asks to stop thebuildandservedaemons first. Lint, format, type checks and unit tests don’t take the lock and stay plainpnpm.
Worktrees
Each linked worktree of the frontend can run its own servers next to the main checkout’s, so a second session can browser test its own branch without waiting for the shared checkout. dot ha works out which checkout it runs in, and in a worktree core, build and serve are that worktree’s own daemons:
| Target | Daemon | URL |
|---|---|---|
core |
ha-frontend-<worktree>/dev |
https://dev.<worktree>.ha-frontend.localhost |
build |
ha-frontend-<worktree>/build |
Through the worktree’s Core |
serve |
ha-frontend-<worktree>/serve |
https://serve.<worktree>.ha-frontend.localhost |
<worktree> is the worktree’s directory name in lowercase, with anything other than letters and digits turned into -. build, dev and serve are refused, as they would shadow the main checkout’s hostnames.
dot ha core dev(ordot ha dev) starts a throwaway Core dev instance for the worktree. It runs Core from the Core checkout’s virtual environment, serves the worktree’s own watch build, and keeps its config in<worktree>/.ha-dev/config, copied fromfrontend.worktree.configthe first time. Onboarding is done for it with the userdevand passworddev. It always runs in the background, and--latestis refused.--freshthrows the instance’s config away and starts again.--onboardingleaves onboarding for you, for testing onboarding itself.dot ha f serve [target]starts the worktree’s ownserve.ha-core/prodaccepts any worktree’s origin; any other Core must allow the worktree’s serve URL in its CORS allowed origins.dot ha statuslists the main checkout’s targets, then each worktree’s.dot ha stopwith no targets in a worktree only stops that worktree’s daemons.- The gallery, demo and e2e suites stay on the main checkout, as their ports are fixed.
Nothing is registered with pitchfork. The first dot ha command in a worktree writes pitchfork.local.toml there, with the namespace ha-frontend-<worktree>, the main checkout’s frontend.toml and frontend-worktree.toml, and adds it and .ha-dev/ to the repository’s info/exclude. A new worktree gets script/bootstrap first when it has no node_modules. Removing the worktree removes its instance.
Core keeps its HTTP settings in .storage/http rather than YAML, so frontend-worktree-dev.sh writes that file before every start, with the port pitchfork picked and trust for the proxy on 127.0.0.1. Logins still go through the login page: trusted_networks can’t tell this machine from anything else coming through the proxy.
Core behind the proxy
The proxy sets Host to localhost:<port> and adds X-Forwarded-* headers. Core rejects those unless it trusts the proxy. In the dev Core, turn on Trust X-Forwarded-For and add 127.0.0.1/32 and ::1/128 to Trusted proxies, under Settings > System > Network > Reverse proxy.
Serving against a remote Core also needs https://serve.ha-frontend.localhost in that instance’s CORS allowed origins, on the same page.
The browser blocks an HTTPS page from calling a plain HTTP Core, so the login works but the frontend can’t connect afterwards. ha-core/prod fronts the prod instance on an HTTPS URL with dot http forward, which drops the proxy’s X-Forwarded-* headers so the remote Core accepts the requests without trusting this machine as a proxy. dot ha f serve prod starts it before serve.
Core only registers the frontend routes if hass_frontend exists when it starts, and a fresh build briefly removes it. ha-core/dev depends on ha-frontend/build, so starting Core starts the build too and waits for it to be ready.
Agents
Agents use the same dot ha commands. Under an agent, dot ha skips setup, Herdr tabs and prompts: it reuses a running daemon, runs suites in the background, and fails with a message instead of stopping a conflicting daemon. dot ha core setup and dot ha logs --follow refuse to run. The Home Assistant workspace AGENTS.md tells agents not to run hass, pnpm dev, pnpm dev:serve or pnpm build directly, and to ask before stopping or swapping a running daemon. It also tells them they can ask to move into a frontend worktree to browser test on its own instance when the main checkout is busy.
Pitchfork config
~/.config/pitchfork/config.toml enables the proxy and registers both repositories as namespaces:
[daemons]
[settings.proxy]
auto_start = false
enable = true
https = true
port = 8443
[namespaces.ha-core]
dir = "/home/<user>/repos/home-assistant/core"
config = ["/home/<user>/.config/dotfiles-private/pitchfork/.config/pitchfork/home-assistant/core.toml"]
[namespaces.ha-frontend]
dir = "/home/<user>/repos/home-assistant/frontend"
config = ["/home/<user>/.config/dotfiles-private/pitchfork/.config/pitchfork/home-assistant/frontend.toml"]
home-assistant/core.toml:
[daemons.dev]
run = "exec .venv/bin/hass -c config"
depends = ["ha-frontend/build"]
port = 8123
ready_port = { port = 8123, timeout = "5m" }
retry = true
stop_signal = { signal = "SIGTERM", timeout = "60s" }
[daemons.prod]
run = "exec dot http forward --port 8126 --target http://homeassistant.local:8123 --cors-origin https://serve.ha-frontend.localhost --cors-suffix .ha-frontend.localhost"
port = 8126
ready_port = 8126
retry = true
--cors-origin and --cors-suffix present a worktree’s https://serve.<worktree>.ha-frontend.localhost origin to prod as the main serve origin, which prod already allows, and hand the browser back its own origin in the response.
home-assistant/frontend.toml:
[daemons.build]
run = "exec env HA_DEV_BACKGROUND=0 pnpm dev --fetch-translations"
ready_output = { pattern = "Build done", timeout = "10m" }
[daemons.serve]
run = """
args="${XDG_STATE_HOME:-$HOME/.local/state}/dot/homeassistant/{{ namespace }}.serve.args"
eval "set -- $(cat "$args" 2>/dev/null)"
exec env HA_DEV_BACKGROUND=0 pnpm dev:serve --fetch-translations -p "$PORT" "$@"
"""
port = { expect = [8124], bump = 10 }
ready_cmd = { run = 'curl -fsS -o /dev/null "http://127.0.0.1:$PORT/"', timeout = "10m" }
The main checkout keeps 8124 while it’s free; a worktree’s serve is bumped off it.
home-assistant/frontend-worktree.toml, only used in worktrees’ pitchfork.local.toml:
[daemons.dev]
run = 'exec "$HOME/.config/pitchfork/home-assistant/frontend-worktree-dev.sh"'
depends = ["build"]
port = { expect = [8140], bump = 10 }
ready_cmd = { run = 'curl -fsS -o /dev/null "http://127.0.0.1:$PORT/manifest.json"', timeout = "5m" }
retry = true
stop_signal = { signal = "SIGTERM", timeout = "60s" }
home-assistant/frontend-worktree-dev.sh writes .ha-dev/config/.storage/http with Core’s own HTTP_STORAGE_SCHEMA (the port, use_x_forwarded_for and trusted proxies 127.0.0.1/32 and ::1/128), then runs hass -c .ha-dev/config with HA_DEV_FRONTEND set to the worktree.
The instance template, ~/.config/dot/homeassistant/dev-config/configuration.yaml:
default_config:
homeassistant:
name: Dev (worktree)
frontend:
development_repo: !env_var HA_DEV_FRONTEND
demo:
kitchen_sink:
dot config
~/.config/dot/homeassistant.yml:
core:
directory: ~/repos/home-assistant/core
workspace: "[HA] Core"
daemon: ha-core/dev
url: https://dev.ha-core.localhost
frontend:
directory: ~/repos/home-assistant/frontend
workspace: "[HA] Frontend"
build: ha-frontend/build
worktree:
config: ~/.config/dot/homeassistant/dev-config
serve:
daemon: ha-frontend/serve
url: https://serve.ha-frontend.localhost
targets:
prod:
title: Prod
url: https://prod.ha-core.localhost
daemon: ha-core/prod
link:
title: Link
url: https://<instance>.ui.nabu.casa