Skip to content
DotfilesDotfiles
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 setup for Core (Git, virtual environment, script/bootstrap), script/bootstrap for the frontend.
  • If the daemon is already running, it asks before restarting it. dot ha dev’s Frontend tab follows a running build instead.
  • --background starts the daemon and returns once it’s ready; otherwise it follows the logs, and Ctrl+C stops it.
  • Every dot ha frontend command takes the frontend’s build lock, so it asks to stop the build and serve daemons first. Lint, format, type checks and unit tests don’t take the lock and stay plain pnpm.

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 (or dot 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 from frontend.worktree.config the first time. Onboarding is done for it with the user dev and password dev. It always runs in the background, and --latest is refused.
  • --fresh throws the instance’s config away and starts again. --onboarding leaves onboarding for you, for testing onboarding itself.
  • dot ha f serve [target] starts the worktree’s own serve. ha-core/prod accepts any worktree’s origin; any other Core must allow the worktree’s serve URL in its CORS allowed origins.
  • dot ha status lists the main checkout’s targets, then each worktree’s. dot ha stop with 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.

Open your Home Assistant instance and show your network configuration.

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

Last updated on