# Homebox Companion: photo-to-inventory capture for Homebox, reviewed

> Homebox Companion is an unofficial FastAPI and Svelte app that sends photos of your belongings to an OpenAI vision model and writes the detected items into an existing Homebox instance. It is convenient if you already run Homebox and accept per-item API costs, and the wrong tool if you want a self-contained inventory with no external model calls.

**Duelion/homebox-companion** — AI-powered companion for Homebox. Snap photos and let AI auto-identify and catalog items into your inventory, then use the AI Chat to organize, search, and update your inventory effortlessly.

- Repository: https://github.com/Duelion/homebox-companion
- Stars: 391 · Forks: 98
- Language: Python
- License: GPL-3.0
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/duelion-homebox-companion

## The gap Homebox Companion fills in a Homebox setup

Homebox is a self-hosted inventory system: you create locations, items, tags and attachments, usually by typing or filling forms. That is fine for a dozen items and tedious for a shelf of camera gear or a box of cables. Homebox Companion targets exactly that moment. The README describes the workflow as taking a photo of your stuff and letting AI identify and catalog items directly into your Homebox instance, with the stated use case of quickly inventorying a room, shelf, or collection. It is a companion app, not a replacement: it authenticates with your existing Homebox credentials, writes through the Homebox API, and stores its own settings and data separately. The project is explicit about its status. The README carries a notice that it is not affiliated with the Homebox project and is an unofficial third-party companion app, and pyproject.toml classifies the package as Development Status 4 - Beta. The audience is therefore narrow and specific: people who already run Homebox, are willing to hold an OpenAI API key, and want the capture step to be a camera rather than a form.

## How the capture pipeline actually works

The flow is a five-step loop, and the README's diagram spells it out: login, select location, capture photos, AI detection, review and edit, submit. Authentication uses your Homebox credentials, so the app is a client of your existing server rather than a new source of truth. Location selection supports browsing the location tree, searching by name, or scanning a Homebox QR code, and new locations can be created on the fly. Photos can be taken or uploaded, with multiple photos per item; the README notes that multi-image analysis from different angles improves accuracy. Detection runs through LiteLLM, which the README describes as a Python adaptor library used to call OpenAI directly, with no local model required unless you want one. The default model is GPT-5 mini; GPT-5 nano is offered as a cheaper alternative that may need more corrections. Detection is not limited to a name: the README says it extracts manufacturer, model, serial number and price when visible, suggests tags from your existing Homebox tags, and supports multiple languages. There is a single-item mode that forces the model to treat a photo as one item, which is the right switch for kits and sets. After detection you review and edit, including telling the AI what it got wrong so it re-analyzes, and you can crop a custom thumbnail per item. Only then does the submit step create items in Homebox with photos attached. The second surface is the AI Chat, which the README says exposes 21 tools. Eleven are read-only and auto-execute, such as list_locations, search_items, get_statistics_by_tag and get_attachment. Eight are writes that require approval, including create_item, update_item, upload_attachment and ensure_asset_ids. Three are destructive and also require approval: delete_item, delete_location and delete_tag. That split is the most interesting design decision in the project. A chat assistant that can delete inventory records is a real risk, and gating writes and deletes behind an approval step is the correct mitigation; it also means the chat is not a fire-and-forget automation channel.

## Installing Homebox Companion with Docker and running a first capture

The README recommends Docker and ships a docker-compose.yml. Two environment variables matter at minimum: HBC_LLM_API_KEY for your model provider key and HBC_HOMEBOX_URL for your Homebox instance. The compose file also sets HBC_LLM_MODEL to gpt-5-mini and HBC_LOG_LEVEL to INFO, maps port 8000, and mounts ./homebox-companion-data at /app/data. If you want to try the workflow before pointing it at your own server, the README gives a docker run one-liner against the public demo Homebox server, with login demo@example.com and password demo.

```bash
docker run -p 8000:8000 \
  -e HBC_LLM_API_KEY=sk-your-key \
  -e HBC_HOMEBOX_URL=https://demo.homebox.software \
  ghcr.io/duelion/homebox-companion:latest
```

Open http://localhost:8000 and log in with the demo credentials to see the capture and review screens populated against demo data. For your own instance, create a docker-compose.yml with your Homebox URL and key, then bring it up. The README notes that if Homebox runs on the same machine but outside Docker, you should use http://host.docker.internal:PORT as the URL, which is the most common first-run failure. Images are published for both linux/amd64 and linux/arm64, so a Raspberry Pi is supported at the image level.

```yaml
services:
  homebox-companion:
    image: ghcr.io/duelion/homebox-companion:latest
    container_name: homebox-companion
    restart: always
    environment:
      - HBC_LLM_API_KEY=sk-your-api-key-here
      - HBC_HOMEBOX_URL=http://192.168.1.100:7745
      - HBC_LLM_MODEL=gpt-5-mini
      - HBC_LOG_LEVEL=INFO
    ports:
      - 8000:8000
    volumes:
      - ./homebox-companion-data:/app/data
```

Run docker compose up -d, then open http://localhost:8000. The first real use is to pick a location, photograph a small group of items, and check the review screen before submitting. One configuration detail from .env.example is worth reading before you tune anything: environment variables are used only for initial bootstrap. On first boot they create data/settings.yaml, and after that the Settings UI is the source of truth, so editing the compose file later will not change a running instance's configuration. If you prefer to run from source, pyproject.toml requires Python 3.14 or later and exposes a homebox-companion console script pointing at server.app:run.

## Where Homebox Companion breaks down

The dependency on a hosted vision model is the central constraint. Every capture sends your photos to OpenAI, and the README's own cost estimates put typical usage at roughly $0.30 per 100 items with GPT-5 mini or roughly $0.10 per 100 items with GPT-5 nano, with prices stated as of 2025-12-10. That is cheap per shelf and less cheap per house, and it scales with how much you photograph rather than with how much you store. Accuracy is the second constraint, and the project is honest about it: nano is described as three times cheaper but likely to need more corrections, which means the review step is not optional. The README does not document rollback of submitted items, so a bad batch means deleting items through Homebox or through the chat's approval-gated delete_item, not undoing an import. The AI Chat is disabled in demo mode, so the demo does not exercise the tool layer at all. Version compatibility is a real boundary: the README states the app was tested with Homebox v0.21 or later and warns that earlier versions may have different authentication behavior. Finally, if you want an inventory that never leaves your network, this is the wrong tool regardless of how well it works; LiteLLM can point at other providers, but the architecture still assumes an external model endpoint.

## Homebox Companion versus typing into Homebox directly

The honest alternative is Homebox itself. Homebox is the system of record, it is self-hosted, and it already supports locations, tags, custom fields and attachments; you can create every item Homebox Companion would create, by hand, with no API key and no third-party model in the loop. The difference is labor and consistency. Manual entry is slower per item and tends to produce inconsistent naming and missing metadata, because nobody types a serial number they cannot read off the device. Homebox Companion's value is that the detection step proposes manufacturer, model, serial number and price, and suggests tags from tags you already use, so the review step is correction rather than composition. The trade-off is that you have added two dependencies, an OpenAI key and a container, and you have accepted that a model's guess is the starting point for your inventory records. There is also a licensing difference worth noting: Homebox Companion is GPL-3.0-or-later, and it is an independent project rather than a Homebox component, so its release cadence and compatibility guarantees are its own.

## Maintenance, licensing and the release cadence

The repository is not archived, and the last push was on 2026-07-06. Releases are recent and versioned: v3.0.0, v3.0.1 and v3.0.2 all landed in June 2026, with v3.0.2 on 2026-06-14. That pattern suggests a project that is being iterated on, but the pyproject.toml classifier still reads Development Status 4 - Beta, which is the right expectation to set for a tool that writes into your inventory. Upgrade cost is low if you use the published image: pull ghcr.io/duelion/homebox-companion:latest and restart the container, keeping the ./homebox-companion-data volume intact. The Dockerfile builds the Svelte frontend in a Node stage and the Python service in a python:3.14-slim stage, runs as a non-root appuser, and defines a health check against /api/version, so container health is observable without extra tooling. The licence is GPL-3.0-or-later, declared both in pyproject.toml and in the LICENSE file. If you plan to modify and redistribute it, or to embed it in a product, the copyleft terms are the thing to have a lawyer read; this article is not legal advice. Running it privately for your own household inventory is the ordinary case the licence is designed for.

## Conclusion

Adopt Homebox Companion if you already run Homebox v0.21 or later, are comfortable sending photos to OpenAI, and want to catalog a room or shelf faster than typing entries by hand. Skip it if you need a fully offline inventory, or if you object to a GPL-3.0-or-later derivative that is explicitly not affiliated with the Homebox project. Before deploying, confirm three things in your own environment: that your Homebox version matches the tested v0.21+ baseline, that HBC_HOMEBOX_URL is reachable from inside the container (host.docker.internal when Homebox runs outside Docker on the same machine), and that the data volume at ./homebox-companion-data is backed up, because the README does not document rollback of submitted items.

## FAQ

### Is Homebox Companion an official Homebox project?

No. The README states plainly that it is not affiliated with the Homebox project and describes itself as an unofficial third-party companion app. It authenticates with your Homebox credentials and writes through the Homebox API.

### Do I need an OpenAI API key to use Homebox Companion?

Yes. The README lists an OpenAI API key as a requirement and the compose example passes it as HBC_LLM_API_KEY. LiteLLM is used to call OpenAI directly, and the README says no local AI model is required unless you want one.

### How much does Homebox Companion cost to run per item?

The README estimates roughly $0.30 per 100 items with GPT-5 mini, the default, and roughly $0.10 per 100 items with GPT-5 nano. It notes nano is cheaper but may need more corrections, with prices stated as of 2025-12-10.

### Which Homebox version does Homebox Companion support?

The README says it was tested with Homebox v0.21 or later and warns that earlier versions may have different authentication behavior. Check your version before deploying.

### Can Homebox Companion delete items from my inventory?

Yes, but only through approval. The README lists delete_item, delete_location and delete_tag as destructive tools that require approval, alongside write tools such as create_item and update_item.

### Does Homebox Companion need a local AI model?

No. The README states that LiteLLM is used to call OpenAI directly and that no local AI model is required unless you want one. An API key is the minimum requirement.

## Sources

- [Duelion/homebox-companion on GitHub](https://github.com/Duelion/homebox-companion)
- [Issues](https://github.com/Duelion/homebox-companion/issues)
- [License: GPL-3.0](https://github.com/Duelion/homebox-companion/blob/main/LICENSE)
- [README](https://github.com/Duelion/homebox-companion/blob/main/README.md)
- [Releases](https://github.com/Duelion/homebox-companion/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/duelion-homebox-companion