Installation

Navet Dev

Navet Dev is the frequently updated development channel for testing changes before a stable release. It can contain unfinished features and regressions. Keep a Home Assistant backup and a copy of important Navet dashboard configuration before switching to it.

Choose An Installation

Installation	Published Dev channel	Best for
HACS custom panel	No	Stable, Home Assistant-hosted Navet
Home Assistant add-on	Yes: `Navet Dev`	Easiest Home Assistant development build
Standalone Docker	Yes: `dev` and `edge` tags	Independent app, testing, and rollback control

Navet Dev publishes update the add-on and Docker images. They intentionally do not publish HACS updates. If you need the current development build inside the Home Assistant custom panel, use the advanced manual build below or choose the Navet Dev add-on instead.

Home Assistant Add-on

This is the recommended development installation for Home Assistant OS and Supervised users.

Requirements

Home Assistant with add-on support
an amd64 or aarch64 system

Install

In Home Assistant, open Settings -> Add-ons -> Add-on Store.
Open the store menu, choose Repositories, and add:
```
https://github.com/awesomestvi/navet
```
Reload the Add-on Store if the repository does not appear immediately.
Open Navet Dev and select Install.
Start the add-on.
Enable Show in sidebar, or select Open Web UI.

The add-on runs through Home Assistant Ingress and reuses the authenticated parent Home Assistant session. It does not need a Home Assistant URL or long-lived access token in normal Ingress use.

The optional direct port is disabled by default. Opening the add-on outside Ingress changes it to the standalone-style OAuth flow.

Update

Each Navet Dev publish advances the version in the add-on repository. Home Assistant will show an update when it refreshes that repository.

Open Settings -> Add-ons -> Navet Dev.
Create a Home Assistant backup if the update is important to your setup.
Select Update, then restart the add-on.

If an update is not visible, reload the Add-on Store and check for updates again.

Optional Home Assistant Chrome Hiding

The add-on cannot install Home Assistant frontend modules by itself. To let Navet hide the native Home Assistant header and sidebar, also install the stable Navet HACS integration and add this to configuration.yaml:

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

Restart Home Assistant after changing configuration.yaml. The shell module is supplied by the HACS integration; the dashboard itself can still come from the Navet Dev add-on.

Standalone Docker

The moving dev and edge tags point to the same latest Navet Dev publication. Use dev unless you already standardize on edge.

Requirements

Docker with Compose support
a Home Assistant URL reachable by the browser that opens Navet

Install

Create compose.yaml:

services:
  navet-dev:
    image: ghcr.io/awesomestvi/navet:dev
    container_name: navet-dev
    restart: unless-stopped
    ports:
      - "8081:80"
    environment:
      NAVET_HASS_URL: "http://homeassistant.local:8123"
    volumes:
      - navet-dev-data:/data

volumes:
  navet-dev-data:

Change NAVET_HASS_URL to the browser-reachable URL of your Home Assistant instance. You may omit it and select Home Assistant during first-run discovery instead. Do not use a container-only hostname unless the browser can also resolve it.

Start Navet Dev:

docker compose up -d

Open http://localhost:8081 and complete Home Assistant OAuth login. Port 8081 lets this Dev container run alongside a stable Navet container using port 8080. Navet stores OAuth and dashboard profile state in the /data volume.

Update

docker compose pull
docker compose up -d

The named volume remains in place when the container is replaced.

Pin Or Roll Back

Moving tags change with every Dev publish. For reproducible installations, replace dev with an exact version from a navet-dev-* GitHub prerelease, for example:

image: ghcr.io/awesomestvi/navet:0.8.0-dev.YYYYMMDDHHMMSS

Use a real published version in place of the example timestamp, then run:

docker compose pull
docker compose up -d

To return to stable Docker, change the image tag to latest.

HACS Custom Panel

HACS installs the stable Navet custom-panel release from https://github.com/awesomestvi/navet-hacs. The Navet Dev publish workflow does not update that repository, so there is no supported Navet Dev HACS channel.

For the supported stable installation:

Add https://github.com/awesomestvi/navet-hacs to HACS as an Integration custom repository.
Install Navet.
Restart Home Assistant.
Add Navet from Settings -> Devices & services.

Do not add the main awesomestvi/navet monorepo to HACS. Its root is an add-on repository, not a publishable HACS integration repository.

Advanced: Build The Current Custom Panel Source

This path is for contributors who specifically need current source inside the Home Assistant custom panel. It is a manual custom integration installation and will not be managed or updated by HACS.

Requirements:

Git
Node.js ^20.19.0 or >=22.12.0
pnpm 11 through the repository’s pinned package manager
access to the Home Assistant /config directory

On a development machine:

git clone https://github.com/awesomestvi/navet.git
cd navet
corepack enable
pnpm install
pnpm build:ha-panel

Then:

Stop Home Assistant and back up any existing /config/custom_components/navet directory.
Copy the contents of platform/home-assistant/custom_components/navet/ into /config/custom_components/navet/.
Start Home Assistant.
Add or reload Navet from Settings -> Devices & services.
Hard-refresh the browser if it still has an older panel bundle cached.

Repeat the build and copy steps to update. Installing or redownloading Navet from HACS can replace this manual build with the latest stable release.

Return To Stable

Add-on: stop Navet Dev, install or start the stable Navet add-on, and verify its configuration.
Docker: change ghcr.io/awesomestvi/navet:dev to ghcr.io/awesomestvi/navet:latest.
Custom panel: install or redownload Navet from the awesomestvi/navet-hacs repository and restart Home Assistant.

Development and stable installations may not share the same storage location. Export important dashboard configuration before switching rather than assuming it will appear in the other runtime.

Troubleshooting

Add-on missing: verify the main repository URL was added to the Add-on Store, then reload it.
Docker cannot find Home Assistant: confirm NAVET_HASS_URL is reachable from both the browser and the Navet container; avoid localhost when Home Assistant runs on another host.
OAuth loops after changing hostnames, TLS, reverse proxies, or ports: sign in again so Navet can create a session for the current Home Assistant URL.
Custom panel still shows an older build: restart Home Assistant and hard-refresh the browser.
HACS offers only stable versions: this is expected; use the add-on or Docker for published Dev builds.

For stable Home Assistant setup and runtime details, see the Home Assistant guide.