Nova HA Dashboard

Nova HA Dashboard is a local Home Assistant control surface for a smart-home setup. It is a Next.js app served on the local network, designed for desktop, wall-mounted and touch-screen use in both portrait and landscape orientations.

The dashboard is configured through a portable, versioned JSON schema. Shipped defaults live in config/dashboard-config.default.json; runtime imports live under data/dashboard-config.json by default and are preserved across Nova deployments.

What It Does

• Reads rooms, devices, entity state, brightness, and colour information from Home Assistant.
• Provides zone-level controls for lights, switches, climate, fans, and related entities.
• Shows a cyber-styled portrait/landscape dashboard for daily use.
• Includes live colour selection, brightness control, router status, and a digital clock.
• Excludes special-case devices, such as the outside light, from broad inside/everything actions.
• Polls and refreshes local state so multiple open dashboard clients stay reasonably current.

Local Development

Install dependencies:

npm install

Run the development server:

npm run dev

Build for production:

npm run build

Run tests:

npm run test

Validate the packaged agent skill:

npm run package:skills

Configuration

Open /config to export the active portable config, download the JSON Schema, validate a draft import, import a config, and review missing runtime secrets.

Configuration APIs:

• GET /api/config: current portable config plus setup status.
• PUT /api/config: validate and apply a portable config.
• GET /api/config/schema: JSON Schema 2020-12 export.
• POST /api/config/validate: dry-run an import.
• GET /api/config/client: non-secret client config for browser surfaces.

Portable exports intentionally exclude tokens, passwords, private runtime paths, and other machine-local secrets.

Start a production server:

npm run start

Environment

The app expects Home Assistant connection settings from environment variables:

• HA_URL: Home Assistant base URL, defaulting to http://127.0.0.1:8123.
• HA_TOKEN: a Home Assistant long-lived access token.
• NOVA_DASHBOARD_CONFIG: optional runtime config path, defaulting to data/dashboard-config.json.
• NOVA_DASHBOARD_MCP_TOKEN: bearer token required for MCP POST calls when MCP auth is enabled.
• ICLOUD_USERNAME: optional Apple ID email for CalDAV Calendar/Reminders sync.
• ICLOUD_APP_PASSWORD: optional Apple app-specific password for CalDAV sync.
• ICLOUD_CALENDARS: optional comma-separated allow-list of iCloud calendar names.
• ICLOUD_REMINDERS: optional comma-separated allow-list of iCloud reminder list names.
• ICLOUD_SYNC_DAYS: optional forward sync window in days, defaulting to 7.

Production secrets live on Nova, not in this repository.

The dashboard also stores small global runtime preferences, such as the last aircon settings chosen from Nova, under data/. These files are ignored by Git.

MCP and Agent Setup

The dashboard exposes a general MCP-compatible JSON-RPC endpoint at POST /api/mcp. GET /api/mcp returns the advertised tools, resources, prompts, and endpoint metadata. The old task endpoint at /api/tasks/mcp remains as a compatibility shim.

MCP tools cover config export/validation/apply, setup status, Home Assistant discovery, dashboard health/state, zone/entity control, and task management. Mutating tools require confirm: true, and MCP POST calls require Authorization: Bearer <NOVA_DASHBOARD_MCP_TOKEN> when auth is enabled.

Agent materials ship in two forms:

• skills/nova-dashboard-management/: Codex skill package for repo/install agents.
• public/agent/nova-dashboard-mcp.json and /agent/skills/nova-dashboard-management/SKILL.md: deployed metadata and skill instructions for other agents.

Deployment Notes

The live deployment runs on Nova under /opt/nova-ha-dashboard and is managed by nova-ha-dashboard.service. Typical changes are built locally first, copied to Nova, rebuilt there, and then the service is restarted.

Generated files, build output, browser artifacts, local environment files, and dependencies are ignored by Git.