HomeAssistantShare — HA bridge + Android app

Three components:

1. addon/homeassistantshare/ — Home Assistant OS add-on (FastAPI + SQLite, per-user entity filtering and HA service proxy).
2. android/ — Android app (Kotlin + Compose) for phones, plus a clock that shows up in Android Auto as a media app.
3. Admin UI — served behind the add-on's HA Ingress at Settings → Add-ons → HomeAssistantShare → Open Web UI.

For the architecture / decisions overview, read CLAUDE.md.

---

1. Install the add-on on Home Assistant OS

A. As a custom repository (recommended once you push to Git)

1. Push this repo to GitHub (e.g. https://github.com/<you>/skynet-ha). The top-level repository.yaml makes it a valid HA add-on repository.
2. In HA: Settings → Add-ons → ⋮ (top right) → Repositories.
3. Paste the GitHub URL → Add.
4. The "HomeAssistantShare" add-on appears in the store. Install it, then start.

B. Local install (faster for development)

1. Enable the SSH & Web Terminal or Samba add-on.
2. Copy addon/homeassistantshare/ into the host's /addons/local/homeassistantshare/.
3. Settings → Add-ons → ⋮ → Check for updates → "HomeAssistantShare" appears under Local add-ons. Install it, then start.

First-run

On first start the add-on creates a bootstrap admin and writes the password into /data/bootstrap_admin.txt inside the add-on container (visible from Logs as a warning, also persisted to the add-on's /data volume — read it with the SSH add-on under /usr/share/hassio/addons/data/<slug>/bootstrap_admin.txt or via the add-on's Filesystem → /data).

Bootstrap admin is only for opening the admin UI, where you create real users. Delete it (or disable + change its password) after setup.

Reach the API publicly

The add-on exposes port 8099 internally. To make the Android app reach it via https://skynet.soltea.it, point the existing reverse proxy at http://homeassistant:8099/api/v1/ (the /api/admin/* and /api/docs paths are protected: admin requires the HA Ingress header, docs is informational only — feel free to also block them at the proxy if paranoid).

Example NGINX block (Hass.io NGINX Proxy add-on):

location /api/v1/ {
    proxy_pass http://a0d7b954-homeassistantshare:8099;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # Never forward a client-supplied ingress header: /api/admin/* trusts
    # its presence as proof the request came from HA. See docs/google-home.md.
    proxy_set_header X-Ingress-Path "";
}

MCP server (optional)

The add-on can also speak MCP at POST /mcp, exposing the same per-user filtered entities to an MCP consumer such as ChatGPT Realtime. Off by default; turn on the mcp_enabled option, mint a service token from the admin UI, and add a /mcp location to the proxy — full walk- through in docs/mcp.md.

Moving the install (export / import)

All the add-on knows lives in its /data volume (skynet.db plus jwt_secret), and that volume does not survive re-installing the add-on from a different repository. The admin UI has an Export / import data panel that writes the whole dataset — users, per-entity permissions, Google links, MCP service principals, optionally the JWT signing secret — into one JSON file, and reads it back with upsert semantics (never deletes; conflicting rows need an explicit Overwrite).

That is also the recipe for the GitHub → Forgejo move, since the canonical repository is now https://git.soltea.it/Soltea-org/skynet-ha: step-by-step in docs/export-import.md.

---

2. Build the Android app

Open android/ in Android Studio Hedgehog (2023.1) or newer. Recommended run config:

• Variant debug points to https://skynet.soltea.it/.
• For internal testing on Android Auto, build a release AAB and upload to Play Console Internal testing (see §3).

Local debug build:

cd android
.\gradlew.bat assembleDebug
adb install app\build\outputs\apk\debug\app-debug.apk

Test Android Auto without a car

1. Install Android Auto on the phone (Play Store).
2. In Android Auto's settings → tap Version 7 times → enable Developer settings → check Unknown sources.
3. Install the Desktop Head Unit (DHU) from the Android SDK manager (SDK Manager → SDK Tools → Android Auto Desktop Head Unit Emulator).
4. Plug the phone via USB (with USB debugging on), launch DHU, open Sharing Home Clock from the head unit's media picker.

---

3. Publish to Play Store

Android Auto only sees the clock media app (uses name="media"); the IOT gate grid was dropped because it did not pass Google's review. Iter:

1. Sign the AAB with an upload key (Android Studio → Build → Generate Signed Bundle). Keep the key safe — losing it locks the listing.
2. Play Console → create app → fill out store listing.
3. Under App content → Cars, declare Android Auto as a media app.
4. Upload the AAB to Internal testing. Add yourself as a tester. Wait for the Play review (typically 1–3 business days for new listings).
5. Once approved, promote to Closed testing (family circle), then Production.

---

4. Local development of the backend (without HA)

cd addon\homeassistantshare\app
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# point at a real HA instance for testing
$env:DATA_DIR = "$PWD\.dev-data"
$env:SUPERVISOR_TOKEN = "<long-lived access token from HA user profile>"
# override the default supervisor URL since we're not inside HA OS:
# (config.py reads HA_API_BASE only via env after this small change — see below)
$env:HA_API_BASE = "https://skynet.soltea.it/api"
$env:CORS_ORIGINS_JSON = '["http://localhost:5173"]'

uvicorn main:app --reload --port 8099

Notes:

• app/config.py currently sets ha_api_base = "http://supervisor/core/api" as the default. For dev override, add ha_api_base: str = os.environ.get("HA_API_BASE", "http://supervisor/core/api") (one-line edit — kept default-only on purpose so production cannot accidentally be pointed away from the supervisor proxy).
• API docs available at http://localhost:8099/api/docs.

---

5. Repository layout

See CLAUDE.md for the full layout, conventions, and the "things to NOT do" section.