ha-homebox-addon

Homebox as a Home Assistant Supervisor Add-on, with a built-in conversation agent so you can ask HA "where is my X?". Runs 100% locally — no cloud required.

---

How it works

The add-on builds Homebox from source with the Nuxt frontend compiled for the HA ingress path (/homebox/). At runtime an nginx sidecar rewrites all paths to the real ingress URL — this is the same pattern used by the official Mealie add-on and is the architecturally correct way to serve a single-page app through HA ingress.

Browser ─► HA Ingress ─► nginx (8099) ─► Homebox Go server (127.0.0.1:7745)
                           └─ sub_filter: /homebox/ → /api/hassio_ingress/TOKEN/

First install note: the add-on builds from source (Node.js frontend + Go backend). Expect ~10 minutes on first install. Subsequent starts use Docker layer cache and are fast.

---

Installation

1 — Add-on (runs the Homebox server locally)

Click to add this repository, then install Homebox:

Or manually:

1. Settings → Add-ons → Add-on Store → ⋮ → Repositories
2. Add https://github.com/Amantux/ha-homebox-addon
3. Install Homebox, set your timezone, click Start
4. The Homebox panel appears in your sidebar — click it to open the UI

2 — Conversation Integration (ask HA about your inventory)

Click to set up the integration:

Or manually:

1. Copy custom_components/homebox/ into your HA config/custom_components/ folder
2. Restart Home Assistant
3. Settings → Integrations → Add → Homebox
4. Enter:
   • URL: http://localhost:7745 (internal Homebox port — use this even though the UI is on ingress)
   • API Token: create one in Homebox at Profile → API Tokens
5. Settings → Voice Assistants → set conversation agent to Homebox

Ask things like:

• "Where is my hammer?"
• "What's in the garage?"
• "Find the camping tent"
• "Search for power tools"
• "Show me everything in the basement"
• "What's stored in the attic?"

Lovelace Search Card

See homebox/DOCS.md for a ready-to-paste dashboard card with a search input and inline results.

Repository Structure

repository.json                     ← HA add-on store manifest
homebox/                            ← Supervisor add-on
  Dockerfile                        ← 4-stage build: clone → node → go → alpine
  config.json                       ← Add-on manifest (ingress, arch, options)
  nginx.conf.tpl                    ← nginx ingress proxy template
  run.sh                            ← Entrypoint: reads Supervisor API, starts nginx + Homebox
  CHANGELOG.md                      ← Add-on changelog (read by HA Supervisor UI)
  DOCS.md                           ← Add-on docs + Lovelace card example
custom_components/homebox/          ← HA custom integration (conversation agent)
tests/                              ← pytest suite — 50 tests, no HA install required