Setup Infrastructure

Setup Infrastructure

This skill configures the mechanical layer: HA API connectivity, SSH access, and initial config pull. It is idempotent — run it any time to verify or repair the connection without affecting your actual configuration.

Step 1: Data Consent & Privacy Mode

Only ask once per session. If the user already consented during an earlier invocation of this skill in the same conversation, skip this step entirely.

1a. Data consent — Before reading any Home Assistant data, inform the user:

"This skill will connect to your Home Assistant instance and read your entity registry, automation configs, and documentation files. This data is sent to Anthropic's API as part of this Claude conversation. See PRIVACY.md for full details. Continue? (yes / no)"

If the user says no, stop here and explain they can still use the repo manually.

1b. Privacy mode offer — Only ask if consent was given. Only ask once per session.

First check if privacy mode is already active: test -f .claude/privacy-patterns. If it is, say "Privacy mode is already enabled" and skip the offer.

If not active, ask:

"Would you like to enable privacy mode? This blocks Claude from directly reading your credentials, personal data files, and runtime state. Setup still works — shell commands handle connectivity. You can toggle this later with make privacy-on / make privacy-off. Enable privacy mode? (yes / no)"

If yes: cp .claude/privacy-patterns.example .claude/privacy-patterns If no: proceed without it.

Step 2: Check .env

Check whether .env exists in the repo root:

bashCopy code
test -f .env && echo "exists" || echo "missing"

If missing: Tell the user to copy .env.example to .env and fill in:

HA_REMOTE_PATH note: HA OS with the SSH add-on typically uses /homeassistant/, while HA Container/Supervised uses /config/. If unsure, the SSH test in Step 4 will auto-detect the correct path.

IMPORTANT: The .env file must NOT use inline comments on value lines (e.g. HA_HOST=foo # comment). Makefile's include treats everything after = as the value, including # ... text. Use only full-line comments (lines starting with #).

Wait for the user to fill in .env before continuing.

If exists and privacy mode is OFF: Load the values and proceed.

If exists and privacy mode is ON (test -f .claude/privacy-patterns): Tell the user: "Privacy mode is active — I can't read .env directly. Please verify it has HA_TOKEN, HA_URL, HA_HOST, SSH_USER filled in. The next step will validate your connection." Then proceed to Step 3 — the curl test validates the values work via source .env (shell sourcing is intentionally not blocked by privacy mode).

Step 3: Validate HA API Token

Test the HA API is reachable:

bashCopy code
source .env && curl -sf -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/" | python3 -c "import sys,json; d=json.load(sys.stdin); print('HA version:', d.get('version','unknown'))"

• Success: Print the HA version and continue.
• Failure: Show the curl error. Common fixes:
  • Token expired → generate a new one at HA → Profile → Security
  • Wrong URL → check if HA is running, try http:// vs https://
  • Network unreachable → ensure you're on the same network, or check VPN/Nabu Casa

Step 4: Validate SSH Connectivity

Test SSH access (required for make pull / make push).

IMPORTANT: Always include $SSH_USER@ in the SSH command. The .env has a separate SSH_USER variable (usually root) — do NOT connect as the local macOS/Linux user.

bashCopy code
source .env && ssh -o ConnectTimeout=5 -o BatchMode=yes "$SSH_USER@$HA_HOST" "echo ok" 2>&1

• Success (ok): Continue to auto-detect HA_REMOTE_PATH.
• Permission denied (publickey): SSH key not authorized. Run:

  bashCopy code
  source .env && ssh-copy-id "$SSH_USER@$HA_HOST"
  

  Or manually add ~/.ssh/id_rsa.pub (or id_ed25519.pub) to the SSH add-on's authorized keys in HA Settings → Add-ons → SSH & Web Terminal → Configuration.
• Connection refused / No route to host: SSH add-on not running or wrong hostname. Check HA Settings → Add-ons → SSH & Web Terminal → Start.

Auto-detect HA_REMOTE_PATH

After SSH is confirmed working, verify that HA_REMOTE_PATH points to the correct directory:

bashCopy code
source .env && ssh "$SSH_USER@$HA_HOST" "test -f ${HA_REMOTE_PATH:-/config/}configuration.yaml && echo 'PATH_OK' || echo 'PATH_WRONG'"

If PATH_WRONG: Try the HA OS default path:

bashCopy code
source .env && ssh "$SSH_USER@$HA_HOST" "test -f /homeassistant/configuration.yaml && echo '/homeassistant/' || (test -f /config/configuration.yaml && echo '/config/' || echo 'NOT_FOUND')"

Update HA_REMOTE_PATH in .env with the correct path before proceeding. If NOT_FOUND, ask the user to verify their HA configuration directory location.

Step 5: Generate Derived .env Files

Once HA API + SSH are confirmed working, generate the derived config files:

dashboard/.env.local (Vite dev server + runtime):

bashCopy code
source .env
cat > dashboard/.env.local << EOF
# AUTO-GENERATED by setup-infrastructure — do not edit manually
# Re-run the setup-infrastructure skill to regenerate.
VITE_HA_URL=$HA_URL
VITE_HA_TOKEN=$HA_TOKEN
VITE_GO2RTC_URL=$VITE_GO2RTC_URL
EOF

Confirm the file was written:

bashCopy code
echo "dashboard/.env.local written"
cat dashboard/.env.local

Step 6: Run make pull

Pull the current HA configuration to the local config/ directory:

bashCopy code
make pull

This syncs automations, scripts, configuration.yaml, and .storage/ (entity/area registry) from your HA instance. The .storage/ files are used by setup-customize for entity discovery.

If make pull fails:

• Check that HA_REMOTE_PATH in .env is correct — HA OS uses /homeassistant/, Container uses /config/
• Verify SSH access in Step 4 (remember to use $SSH_USER@$HA_HOST)
• Check .env has no inline comments (breaks Makefile include)
• Run make pull manually and share the error

Step 7: Verify Python Tooling

Check the Python validation tools work:

bashCopy code
python3 -m venv venv 2>/dev/null || true && source venv/bin/activate && pip install -q pyyaml 2>/dev/null && python tools/yaml_validator.py config/ && echo "Validation tools OK"

If this fails, ensure Python 3.10+ is installed.

Step 8: Install ha-api / ha-ws on HA

Install claude-code-ha CLI tools on the HA instance. These provide ha-api (REST) and ha-ws (WebSocket) for entity management, state queries, service calls, and entity renaming — all accessible via SSH.

bashCopy code
source .env
# Clone path adapts to HA_REMOTE_PATH (tools live alongside configuration.yaml)
ssh "$SSH_USER@$HA_HOST" "test -d ${HA_REMOTE_PATH}claude-code-ha && echo 'ALREADY_INSTALLED' || (cd ${HA_REMOTE_PATH} && git clone https://github.com/danbuhler/claude-code-ha.git && echo 'CLONED')"
ssh "$SSH_USER@$HA_HOST" "bash ${HA_REMOTE_PATH}claude-code-ha/install.sh"

Verify it works:

bashCopy code
source .env && ssh "$SSH_USER@$HA_HOST" "source /etc/profile.d/claude-ha.sh; source ${HA_REMOTE_PATH}.env; ha-api domains"

If this prints entity counts by domain, the tools are working.

Note: HA OS updates reset the root filesystem (symlinks, pip packages). The repo persists at ${HA_REMOTE_PATH}claude-code-ha/ but re-run the install script after each HA OS update: ssh "$SSH_USER@$HA_HOST" "bash ${HA_REMOTE_PATH}claude-code-ha/install.sh"

Step 9: Write setup-state.json Checkpoint

Write a checkpoint so setup-customize knows the infrastructure is ready:

pythonCopy code
import json, datetime, os

state = {
    "schema_version": 1,
    "infrastructure": {
        "ha_url": os.environ.get("HA_URL", ""),
        "configured_at": datetime.datetime.now().isoformat(),
        "steps_completed": ["env", "token", "ssh", "pull", "venv", "ha_tools"]
    },
    "session": {
        "current_phase": "infrastructure_complete",
        "can_resume": True
    }
}
with open("setup-state.json", "w") as f:
    json.dump(state, f, indent=2)
print("Checkpoint saved to setup-state.json")

Run this via: source .env && python3 -c "$(cat << 'PYEOF' ... PYEOF)"— using a quoted heredoc to avoid shell expansion issues with the.env` values.

Step 10: Stamp the kit version anchor

.kit-version records which kit version this install is based on, so the upgrade skill can later compute what changed. It ships with version: already set; this step fills in commit: (the exact kit commit the install is on) so upgrades have a precise, history-independent baseline. Idempotent and ZIP-safe — re-running changes nothing, and an install with no git history still works.

Rules:

• Write only commit: — never touch version: (the shipped value is authoritative; the upgrade skill bumps it later). This avoids any producer/consumer ambiguity.
• Stamp commit: only when it is empty/missing; never overwrite a non-empty value (an upgrade may have advanced it).
• If there is no .git directory or no reachable remote (e.g. a ZIP download), leave commit: "" and continue — version: alone supports baselining. Do not error.

pythonCopy code
import re, subprocess, pathlib

kv = pathlib.Path(".kit-version")
if kv.exists():
    text = kv.read_text()
    m = re.search(r'^commit:\s*"?([^"\n]*)"?\s*$', text, re.M)
    current = (m.group(1) if m else "").strip()
    if not current:
        sha = ""
        try:
            sha = subprocess.run(["git", "rev-parse", "HEAD"], capture_output=True, text=True,
                                 timeout=5).stdout.strip()
        except Exception:
            sha = ""   # no git / ZIP install — leave commit empty, this is fine
        if sha:
            if m:
                text = re.sub(r'^commit:.*$', f'commit: "{sha}"', text, flags=re.M)
            else:
                text = text.rstrip() + f'\ncommit: "{sha}"\n'
            kv.write_text(text)
            print(f"Stamped .kit-version commit: {sha}")
        else:
            print("No git history (ZIP install?) — left .kit-version commit empty")
    else:
        print(f".kit-version already stamped (commit: {current}) — unchanged")
else:
    print(".kit-version not present — skipping stamp")

Completion

Tell the user:

"Infrastructure is ready. Your HA instance is connected and config has been pulled.

Next step: Run setup-customize to map your rooms and entities to the dashboard. Just say: 'set up my home' or 'run setup-customize'."

If the user asks about what was pulled, run ls config/ and show the directory structure.

Troubleshooting Reference