pi-ha — an AI chat for Home Assistant

⚠️ DEPRECATED — superseded by pi-chat + the ha-bridge add-on. This repo is being retired. Home Assistant control now lives in pi-chat (extensions/ha + extensions/ha-bridge), with a thin, stateless ha-bridge add-on replacing this full chat add-on. The replacement add-on is published from the ha-bridge/ directory in THIS repo — install it alongside this (deprecated) add-on. See pi-chat's ha-bridge/README.md for install and migration (scripts/migrate-pi-ha.ts) instructions. No new features are planned for the pi-ha add-on itself.

A self-hosted web chat for controlling and asking about your Home Assistant, backed by the Pi SDK agent runtime. One container — a SvelteKit SPA frontend (in web/) over a framework-free Node server. It installs as a Home Assistant add-on and appears in your sidebar.

Streaming replies, chat history, cross-device sync, and it follows your HA theme (light/dark + colors). It drives your home through HA's API.

⚠️ What you're granting it

This is an LLM with real control of your home — not a read-only dashboard. With a model API key set, it can:

• Read and control your entities — lights, switches, climate, automations, scripts, scenes — and call any HA service
• Read and write your Home Assistant configuration — /config is mounted read-write, so it can edit YAML, automations, and scripts
• Run shell commands on your HAOS host as root — if the Advanced SSH & Web Terminal add-on is installed (it authorizes an SSH key there on first boot)
• Reach your LAN and the web (web search and page fetching)

Install it only if you're comfortable with that. The chat UI is password protected, and HA's own login sits in front of the ingress.

Install (Home Assistant OS)

1. Settings → Add-ons → ⋮ menu → Repositories
2. Add https://host.gsylabs.gg/gyslabsgg/pi-ha.git, then reload
3. Install Pi Home Assistant and configure:
   • web_password — required — the password for the chat UI
   • at least one model API key (see below)
   • default_model — optional — model id used for new chats
4. Start it. It appears in the sidebar.

Requires Home Assistant OS (or a supervised install) — the add-on needs the supervisor. Images are multi-arch: amd64, arm64, armv7.

Model providers

Models appear in the chat's model dropdown once their key is set. All keys are optional; set at least one.

Option	Provider
deepseek_api_key	DeepSeek
anthropic_api_key	Anthropic (Claude)
openai_api_key	OpenAI
gemini_api_key	Google Gemini
groq_api_key	Groq
xai_api_key	xAI (Grok)
mistral_api_key	Mistral
openrouter_api_key	OpenRouter (one key, many models)
serper_api_key	Serper — web-search results (optional)

Host-shell access (SSH)

The ssh_exec tool (running commands on the HAOS host) is optional — HA control and config editing work without it. It connects over SSH using a key stored in /data/ssh, with the connection defined by an ssh_config written at boot. The sidebar shows a green SSH dot when the connection works.

Automatic (default): on first boot the add-on generates an ed25519 key and tries to authorize it on the Advanced SSH & Web Terminal add-on — install that add-on first. If the live SSH test succeeds it does nothing further.

Manual setup — if auto-auth fails, or you want your own key or a different host, either:

• Use the generated key: read it from GET /api/ssh-pubkey and add that line to the target's authorized_keys (Advanced SSH & Web Terminal → Configuration → authorized_keys, or ~/.ssh/authorized_keys on the host).

• Supply your own key: POST /api/ssh-key with your OpenSSH private key:

  { "key": "-----BEGIN OPENSSH PRIVATE KEY-----\n…\n" }
  

  It derives the public key, writes the SSH config, and tests the connection, returning { ok, pubkey }.

Config options:

Option	Default	Purpose
ssh_host	localhost	SSH target — localhost is the SSH add-on on the HAOS host; set a LAN IP to reach a different host
ssh_user	root	SSH login user

Verify with the SSH status dot in the sidebar, or GET /api/ssh-status.

Development

npm install
export WEB_PASSWORD=changeme \
       HOMEASSISTANT_URL=http://<ha-host>:8123 \
       HOMEASSISTANT_TOKEN=<long-lived-token> \
       DEEPSEEK_API_KEY=<key>
npm start   # → http://localhost:3000

The frontend is a SvelteKit SPA in web/; build it into web/build (served by the Node server):

cd web && npm install && npm run build

State (sessions, sql.js database, settings) lives in .pi-data/ (gitignored). Run npm run check to type-check the server and npm --prefix web run check for the client; node test/theme-map-check.mjs, node test/logic-check.mjs, and node test/thinking-flush-check.ts cover the client-logic checks.

Releases are multi-arch images at host.gsylabs.gg/gyslabsgg/pi-ha, built with ./release.sh <patch|minor|major>.

License

MIT — see LICENSE.