Skip to content
Explore
GitHub

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 App Reviewed metadata updates Home Assistant development builds
Standalone Docker Yes: dev, edge, and exact branch versions Independent app, testing, and rollback control

Navet Dev publishes update Docker images, including the image used by the Home Assistant App. They do not change protected App store metadata or publish HACS updates. If you need the current development build inside the Home Assistant custom panel, use the advanced manual build below.

Every named clean branch can publish an immutable exact Dev version. Only a publish sourced from main advances the moving dev and edge image tags. App store metadata changes require normal review through main.

Home Assistant App

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

Requirements

  • Home Assistant OS with Apps support
  • an amd64 or aarch64 system

Install

  1. In Home Assistant, open Settings -> Apps -> App store.

  2. Open the store menu, choose Repositories, and add:

    https://github.com/navet-app/navet

  3. Reload the App store if the repository does not appear immediately.

  4. Open Navet Dev and select Install.

  5. Start the App.

  6. Enable Show in sidebar, or select Open Web UI.

The App runs through Home Assistant Ingress and reuses the authenticated parent Home Assistant session.

The App uses Ingress by default. To test direct access, assign an available host port to the optional direct Navet web interface in Network, restart the App, and complete the separate Home Assistant sign-in. openHAB can be added in Settings -> System with a container-reachable URL and credentials.

Update

Home Assistant shows an update only when reviewed App metadata advances on main. Automatic Dev image publishes do not change that metadata, so the App store does not offer every merged-PR build.

  1. Open Settings -> Apps -> Navet Dev.
  2. Create a Home Assistant backup if the update is important to your setup.
  3. Select Update, then restart the App.

If an update is not visible, reload the App store and check for updates again.

Optional Home Assistant Chrome Hiding

The App 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 App.

Standalone Docker

The moving dev and edge tags point to the latest Navet Dev publication sourced from main. Use dev unless you already standardize on edge. A publish from another branch is available only through its exact immutable version.

Requirements

  • Docker with Compose support
  • the credentials required by the provider you want to test
  • for Home Assistant, a trusted upstream reachable from the Navet container and an authorization address reachable from the browser while signing in; these may be different routes to the same installation

Install

Create compose.yaml:

services:
  navet-dev:
    image: ghcr.io/awesomestvi/navet:dev
    container_name: navet-dev
    restart: unless-stopped
    ports:
      - "8081:80"
    environment:
      # Optional trusted Home Assistant upstream pin.
      NAVET_HASS_URL: "http://homeassistant.local:8123"
      # Optional Homey OAuth client settings.
      NAVET_HOMEY_CLIENT_ID: "your-athom-client-id"
      NAVET_HOMEY_CLIENT_SECRET: "your-athom-client-secret"
    volumes:
      - navet-dev-data:/data


volumes:
  navet-dev-data:

Remove any environment variables for providers you are not testing. For Home Assistant, change NAVET_HASS_URL to an upstream reachable from the Navet container, or omit it and use first-run discovery and sign-in. Without an explicit upstream, Navet uses the address entered in the login form for both authorization and token exchange. With an explicit upstream, browser addresses must reach that same Home Assistant installation. After authorization, Home Assistant API traffic, token renewal, and provider-managed HTTP camera resources use Navet’s same-origin proxy. For Homey, register the exact callback URL described in the Homey guide. openHAB needs no container environment variable; choose it in Navet and enter its base URL and credentials.

Start Navet Dev:

Terminal window
docker compose up -d

Open http://localhost:8081 when Docker runs on this computer, or replace localhost with the Docker host’s LAN, VPN, or public name from another device. Port 8081 lets this Dev container run alongside a stable Navet container using port 8080. Navet stores provider sessions and dashboard profile state in the /data volume.

Update

Terminal window
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 main-backed Dev publish. For reproducible installations or testing a non-main branch publish, replace dev with an exact version from a navet-dev-* GitHub prerelease, for example:

image: ghcr.io/awesomestvi/navet:0.x.y-dev.YYYYMMDDHHMMSS

Use the full published version in place of 0.x.y-dev.YYYYMMDDHHMMSS, then run:

Terminal window
docker compose pull
docker compose up -d

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

The GitHub prerelease identifies the source branch and commit. Confirm those values before using an exact branch build on a household dashboard.

HACS Custom Panel

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

For the supported stable installation:

  1. Add https://github.com/navet-app/navet-home-assistant to HACS as an Integration custom repository.
  2. Install Navet.
  3. Restart Home Assistant.
  4. Add Navet from Settings -> Devices & services.

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:

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

Then:

  1. Stop Home Assistant and back up any existing /config/custom_components/navet directory.
  2. Copy the contents of platform/home-assistant/custom_components/navet/ into /config/custom_components/navet/.
  3. Start Home Assistant.
  4. Add or reload Navet from Settings -> Devices & services.
  5. 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

  • Home Assistant App: stop Navet Dev, install or start the stable Navet App, 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-home-assistant 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

  • App missing: verify the main repository URL was added to the App store, then reload it.
  • Exact branch release missing from the App store: this is expected until its metadata lands on main; use the exact standalone Docker image to test it.
  • Home Assistant authorization page does not open: confirm the address entered in Navet is reachable from the current browser, including through the intended VPN or external route.
  • Home Assistant accepts authorization but returning to Navet fails: confirm NAVET_HASS_URL, or the address entered at sign-in, is reachable from 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 Home Assistant App or Docker for published Dev builds.

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