Installation

Home Assistant

Use this guide when you want Navet to connect to Home Assistant.

To explore the interface without connecting a provider, use the public demo at demo.navet.app. The demo is a separate static deployment and contains sample data only.

Overview

Navet currently supports three Home Assistant deployment paths:

custom panel via HACS
add-on
standalone Docker connected to Home Assistant

To test frequently updated development builds, see Install Navet Dev. Published Dev builds are available for the add-on and Docker; HACS remains stable-only.

Which Path Should You Choose?

Path	Best when	Notes
Custom panel	you want Navet in the Home Assistant sidebar through HACS	Home Assistant-hosted experience
Add-on	you want Home Assistant to package and manage Navet	runs behind Ingress
Standalone Docker	you want Navet as its own app while still connecting to Home Assistant	uses OAuth and stores app state under `/data`

Home Assistant Custom Panel

When To Choose It

Use the custom panel if you want Navet in the Home Assistant sidebar through HACS with the most integrated Home Assistant experience.

Prerequisites

Home Assistant
HACS

Setup Steps

Add https://github.com/awesomestvi/navet-hacs as a custom HACS repository with category Integration.
Install Navet.
Restart Home Assistant.
Add the Navet integration from Settings -> Devices & services.
Optional but recommended for native Home Assistant chrome hiding in the custom panel and add-on: add Navet’s shell module under frontend.extra_module_url:

frontend:
  extra_module_url:
    - /api/navet/static/navet-ha-shell.js

Restart Home Assistant after updating configuration.yaml.
Open Navet from the Home Assistant sidebar.

What To Expect

Navet appears in the Home Assistant sidebar
Home Assistant remains the host environment
If navet-ha-shell.js is loaded through frontend.extra_module_url, Navet can hide the Home Assistant header and sidebar while the custom panel or add-on is open
The shell module is served by the Navet integration at /api/navet/static/navet-ha-shell.js

Troubleshooting

If you previously added https://github.com/awesomestvi/navet to HACS, remove that custom repository and add https://github.com/awesomestvi/navet-hacs with category Integration.

Home Assistant Add-on

When To Choose It

Use the add-on if you want Navet packaged and managed from Home Assistant itself.

Prerequisites

Home Assistant with add-on support

Setup Steps

Open Settings -> Add-ons -> Add-on Store.
Open the repository menu and choose Repositories.
Add https://github.com/awesomestvi/navet as an Add-on Store repository.
Install Navet for stable releases or Navet Dev for the published development channel.
If you want native Home Assistant chrome hiding in add-on mode, also install the Navet HACS integration so Home Assistant can serve /api/navet/static/navet-ha-shell.js to the parent frontend.
Start the add-on and open Navet from the Home Assistant sidebar.
Optional but recommended for native Home Assistant chrome hiding in the add-on: add Navet’s shell module under frontend.extra_module_url:

frontend:
  extra_module_url:
    - /api/navet/static/navet-ha-shell.js

Restart Home Assistant after updating configuration.yaml.

What To Expect

Navet runs behind Home Assistant Ingress
the Home Assistant frontend session is reused through the parent hass runtime bridge
Navet does not open its own Home Assistant websocket while running inside Ingress
If navet-ha-shell.js is loaded through frontend.extra_module_url, Navet can hide the Home Assistant header and sidebar while the add-on is open
That shell module is served by the Navet HACS integration, not by the add-on ingress app
the direct host port is off by default
if you expose the app outside Ingress, Navet falls back to the standalone-style OAuth flow

Troubleshooting

If the add-on opens outside Ingress, expect standalone-style OAuth behavior instead of the parent-session bridge.
The add-on cannot inject host-shell code into Home Assistant by itself. Native Home Assistant chrome hiding in add-on mode requires both the global frontend.extra_module_url entry above and the Navet HACS integration that serves /api/navet/static/navet-ha-shell.js.

Standalone Docker

When To Choose It

Use standalone Docker when you want Navet to run as its own app while still connecting to Home Assistant.

Prerequisites

Docker
a Home Assistant instance reachable from the browser that will open Navet

Setup Steps

Use this docker-compose.yml:

services:
  navet:
    image: ghcr.io/awesomestvi/navet:latest
    container_name: navet
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - navet-data:/data

volumes:
  navet-data:

Start it:

docker compose up -d

Then open http://localhost:8080.

What To Expect

Home Assistant login uses OAuth
dashboard and profile state are stored through same-origin runtime endpoints under /data
if the stored OAuth session becomes invalid during token refresh, Navet clears it and returns to login

Automation And Habit Insights

Home Assistant is currently the provider path that supports native automation details and habit-suggested automation creation.

In the Tasks section, Navet can inspect Home Assistant automation config to show triggers, conditions, actions, diagnostics, and dependent entity states. In Habits, creating a suggested routine writes a Home Assistant automation with a navet_ config key when the rule maps to a safe turn-on or turn-off action. Notify-only habit rules are not created as native Home Assistant automations yet.

Troubleshooting

If Navet repeatedly returns to login, verify that the saved Home Assistant URL still matches your current instance URL.
If you recently changed reverse-proxy, TLS, hostname, or port settings for Home Assistant, sign in again so Navet can obtain a fresh OAuth session.
If the Home Assistant authorization was revoked or the refresh token became invalid, sign in again to recreate the stored session under /data.