z-home

Home automation orchestration platform layered on Home Assistant with local LLM inference via Ollama (Gemma family models).

Architecture

flowchart LR
  subgraph clients [Clients]
    Panel[Control Panel]
    Voice[Google Home via HA]
  end

  subgraph stack [Docker Compose]
    API[z-home API]
    HA[Home Assistant]
    LLM[Ollama]
    DB[(SQLite)]
    Prom[Prometheus]
    Graf[Grafana]
  end

  Panel --> API
  Voice --> HA
  API --> HA
  API --> LLM
  API --> DB
  Prom --> API
  Graf --> Prom

Loading

Monorepo layout

Path	Purpose
apps/api	Fastify REST API with bearer auth
apps/control-panel	React + Vite + Tailwind UI
packages/config	Zod-validated configuration
packages/db	SQLite persistence and migrations
packages/ha-client	Home Assistant client (subtask 02)
packages/ollama-client	Ollama client (subtask 03)

Prerequisites

• Node.js 22+
• pnpm 10+
• Docker and Docker Compose

Getting started

1. Copy environment template and set secrets:

   cp .env.example .env
   # Edit Z_HOME_API_TOKEN, HA_TOKEN, etc.

2. Install dependencies:

   pnpm install
   pnpm build

3. Start the stack:

   docker compose up -d

4. Access services (host ports from .env; defaults match .env.example):

   • Control panel: http://localhost:18080
   • API health: http://localhost:13000/health
   • Home Assistant: http://localhost:8123
   • Grafana: http://localhost:13001
   • Prometheus: http://localhost:19090

5. Pull the Ollama model (first run):

   docker exec z-home-ollama ollama pull gemma3:4b

6. Configure voice control (Google Home → HA → z-home):

   • Copy HA secrets: cp homeassistant/secrets.yaml.example homeassistant/secrets.yaml
   • Set z_home_api_token_header to match Z_HOME_API_TOKEN
   • Follow docs/voice-control/setup-guide.md

Voice control

Google Home voice commands flow through Home Assistant — z-home does not use the Google SDK. Simple commands are handled directly by HA; complex natural-language commands route to z-home's /api/intent endpoint via HA webhook automations.

See docs/voice-control/README.md for setup, entity exposure, examples, and the manual test plan.

API authentication

All /api/* routes require:

Authorization: Bearer <Z_HOME_API_TOKEN>

Development

pnpm --filter @z-home/api dev
pnpm --filter @z-home/control-panel dev
pnpm typecheck
pnpm lint

License

Private — home use.