Home Assistant & Smart Infrastructure Setup (1): Running Home Assistant Core in Docker & Creating a CLI Bridge

Goal: Run Home Assistant Core locally via Docker in host network mode (crucial for local smart home mDNS auto-discovery) and create a script to read sensor states from the terminal.

Why CLI Scripts? (Agentic AI Observability)

Before jumping into the script code, it is important to understand why command-line scripts are extremely useful for modern smart homes. Beyond convenience for terminal users, these CLI scripts act as a programmatic interface (API bridge) for agentic AI assistants like Antigravity (agy).

By exposing Home Assistant states through standard shell scripts, an AI agent running in your workspace can query, check, and verify live IoT metrics or network states autonomously. This enables the agent to check if the network is healthy, read environment levels, or verify configurations without having to scrape web-based dashboards or utilize complex browser interfaces. It bridges human developer terminal workflows with agentic automation.

Step-by-Step Configuration

1. Setup Persistent Directory Structure

Prepare a local configuration directory to preserve settings across container recreations:

mkdir -p /home/gvoina/homeassistant

2. Run the Docker Container

Execute the following docker run command. Note that --network=host is required:

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=Europe/Bucharest \
  -v /home/gvoina/homeassistant:/config \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

3. Access the Dashboard and Generate a Token

1. Open your browser and navigate to http://localhost:8123.
2. Complete onboarding.
3. Click on your profile in the bottom-left corner of the sidebar.
4. Scroll to the bottom and click Create Token under Long-Lived Access Tokens.
5. Name it CLI-Bridge and copy the generated token.
6. Store this token in /home/gvoina/homeassistant/api_token.txt.

4. The CLI Bridge Script

Create /home/gvoina/scripts/get_ha_sensor.sh:

#!/usr/bin/env bash
set -eo pipefail

ENTITY_ID=$1
if [[ -z "$ENTITY_ID" ]]; then
  echo "Usage: $0 <entity_id>"
  exit 1
fi

TOKEN_FILE="/home/gvoina/homeassistant/api_token.txt"
if [[ ! -f "$TOKEN_FILE" ]]; then
  echo "Error: API token not found at $TOKEN_FILE."
  exit 1
fi

TOKEN=$(cat "$TOKEN_FILE" | tr -d '\r\n[:space:]')

RESPONSE=$(curl -s -X GET \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "http://localhost:8123/api/states/$ENTITY_ID")

if echo "$RESPONSE" | jq -e '.state' >/dev/null 2>&1; then
  STATE=$(echo "$RESPONSE" | jq -r '.state')
  UNIT=$(echo "$RESPONSE" | jq -r '.attributes.unit_of_measurement // ""')
  NAME=$(echo "$RESPONSE" | jq -r '.attributes.friendly_name // ""')
  if [[ -n "$UNIT" && "$UNIT" != "null" ]]; then
    echo "$NAME: $STATE $UNIT"
  else
    echo "$NAME: $STATE"
  fi
else
  echo "Error: Failed to fetch state for entity '$ENTITY_ID'."
  exit 1
fi

Make the script executable:

chmod +x /home/gvoina/scripts/get_ha_sensor.sh