Homebox Companion: photo-to-inventory AI for a self-hosted Homebox server

What Homebox Companion adds to an existing Homebox install

Homebox is a self-hosted inventory manager. Its own workflow is manual: you create a location, then type in each item, its fields and its tags. Homebox Companion exists to remove that typing. The README describes the target user directly: someone who wants to inventory a room, a shelf or a collection quickly, by taking photos rather than filling in forms.

The project is explicit that it is not affiliated with Homebox and calls itself an unofficial third-party companion app. That matters for expectations. Companion does not replace Homebox, does not store your inventory as the source of truth, and does not work without a Homebox instance to write into. It authenticates with your existing Homebox credentials and creates items through the Homebox API. If Homebox is down, Companion has nothing to talk to.

The second half of the product is an AI chat assistant that can query and modify the inventory in natural language. The README lists 21 tools: read-only tools such as list_items, search_items and get_statistics execute automatically, while write tools such as create_item and update_item and destructive tools such as delete_item require an approval step before they run. That approval gate is the most interesting design decision in the project, and it is the reason the chat is not simply a thin wrapper around the API.

The photo-to-item pipeline, step by step

The README's flow diagram gives six stages: login, select location, capture photos, review and edit, submit. AI detection sits between capture and review.

Authentication happens against Homebox, not against Companion. You then pick a target location by browsing the hierarchical location tree, searching by name, or scanning a Homebox QR code. Photos come from the camera or an upload, and the README notes that multiple photos per item are supported, which is presented as a way to improve accuracy by shooting the same object from several angles. A single-item mode forces the model to treat a photo as one object, which is aimed at sets and kits where the model would otherwise split a boxed set into separate entries.

The vision call goes 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 roughly three times cheaper with more corrections expected. The README's own estimate is about $0.30 per 100 items on mini and about $0.10 per 100 items on nano, with prices stated as of 2025-12-10.

Detection returns names, quantities and metadata, and the README says the model extracts manufacturer, model, serial number and price when those are visible, and suggests tags drawn from tags that already exist in your Homebox. Everything lands in an editable review screen. You can correct fields by hand, or tell the AI what it got wrong and have it re-analyze. Only after review are items created in Homebox with their photos attached.

Installing Homebox Companion with Docker Compose

The README recommends Docker. The repository ships a docker-compose.yml with the image ghcr.io/duelion/homebox-companion:latest, a published port of 8000, and a bind mount at ./homebox-companion-data mapped to /app/data. Two environment variables are required: HBC_LLM_API_KEY and HBC_HOMEBOX_URL. The compose file also sets HBC_LLM_MODEL=gpt-5-mini and HBC_LOG_LEVEL=INFO.

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

Note the port in HBC_HOMEBOX_URL: the README's examples use 7745, and the compose file comment says to use your Homebox URL with port, or a domain if Homebox sits behind a reverse proxy. If Homebox runs on the host outside Docker, the README suggests http://host.docker.internal:PORT instead of a LAN address.

Start it and open the web UI. The container's health check polls /api/version every 30 seconds, so a failing start usually shows up as an unhealthy container rather than a silent one.

docker compose up -d

The README states the images are built for both linux/amd64 and linux/arm64, so Raspberry Pi and ARM hosts are covered. There is also a one-liner for testing against the public demo server, which logs you in with demo@example.com and the password demo:

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

For a first real use, point HBC_HOMEBOX_URL at your own Homebox, log in with your Homebox credentials, choose a location, photograph one shelf, and check the review screen before submitting. The .env.example file notes something worth reading twice: on first boot the environment variables create data/settings.yaml, and after that configuration is managed through the Settings UI. Environment variables are bootstrap only. Editing them later and restarting will not necessarily override what is already in settings.yaml.

Where the design gets in your way

The dependency on a hosted vision model is the largest constraint. The README frames LiteLLM as a way to call OpenAI directly with just your API key, and the cost table is written in OpenAI's published prices. Every photo you submit leaves your network and is processed by a third party. For a household inventory that is probably acceptable; for anything you would not photograph and upload, it is not. The README does mention that a local model is possible if you want one, but it does not document a working local configuration, so treat that as unproven rather than as an escape hatch.

Accuracy is priced, not guaranteed. The README's own wording is that gpt-5-nano may need more corrections, which means the cheap path costs you review time rather than money. There is no accuracy figure published anywhere in the repository, and no benchmark. You will find out what your photos look like to the model only by running it.

The chat assistant is asymmetric in a way worth understanding before you use it. Read-only tools run without asking. Write and delete tools require approval. That is the right default, but it means the assistant cannot be handed a bulk cleanup task unattended. The README also notes that AI Chat is disabled in demo mode, so the demo shows you detection and not the assistant.

Finally, version compatibility is narrow and stated plainly: tested with Homebox v0.21+, and earlier versions may have different authentication behavior. pyproject.toml requires Python 3.14 or newer and classifies the project as Development Status 4 - Beta. The last push to the repository was on 2026-07-06, and the newest release is v3.0.2 from 2026-06-14. That is recent, but this is a beta-flagged third-party add-on, not a project with a long support history.

Homebox Companion versus Grocy and versus Homebox alone

The honest comparison is not against another AI photo cataloger. It is against doing the work yourself in Homebox, and against Grocy if what you actually want is consumption tracking.

Homebox alone is free, offline, and entirely under your control. Its weakness is data entry: every item is typed. Companion trades that typing for an API key and a review pass. If you are cataloging twenty items, the trade is bad. If you are cataloging a garage, it is good. The two are complementary rather than competing, since Companion writes into Homebox and cannot exist without it.

Grocy is a different kind of tool. It is built around groceries, stock quantities and expiry dates, which is a purchasing and consumption workflow. Homebox is built around where a thing is and what it is. Companion's photo detection, tag suggestions and location tree are all oriented toward the second question. If your problem is knowing that you have three cans of tomatoes and they expire next month, Companion and Homebox are the wrong pair. The RELATED SEARCHES list contains a direct Grocy versus Homebox query, and the distinction above is the reason that comparison keeps coming up.

Within the AI-photo space, the meaningful difference is the approval workflow and the tool surface. Companion exposes 21 named tools against the Homebox API with an explicit approval step for anything that writes or deletes, rather than a free-form agent that can call whatever it likes. That is a smaller, more predictable design, and it is the part of the project most worth copying.

Licence and the cost of keeping it running

Homebox Companion is licensed GPL-3.0-or-later, per pyproject.toml and the LICENSE file. The README's disclaimer that it is not affiliated with the Homebox project means the two codebases are separate works with separate maintainers. If you plan to modify Companion and distribute it, or to bundle it into a product, the copyleft terms of GPL-3.0 are your problem to read, not something this article can settle.

Running costs are the API bill plus your own hardware. The README's estimate is roughly $0.30 per 100 items on gpt-5-mini and roughly $0.10 per 100 items on gpt-5-nano, with the caveat that nano needs more corrections. Those numbers are per-item detection, not per-photo, so photographing the same shelf from three angles is not three times the item cost but is more image input than one shot. The README does not break out per-image pricing, so budget from your own usage rather than from that table.

Upgrade cost is low if you use the published image: change the tag and restart. The friction is configuration. Because .env.example states that environment variables only bootstrap data/settings.yaml on first boot, a container that has already run will not pick up changed env vars. Keep the ./homebox-companion-data volume, and re-check the Settings UI after an upgrade rather than assuming your env file still governs. The project also pins Python 3.14 in pyproject.toml and installs with uv in its Dockerfile, so a source install means matching that interpreter version.

Editorial conclusion

Adopt Homebox Companion if you already run Homebox, are comfortable pasting an OpenAI API key into a container, and want to catalog a room by photographing a shelf instead of typing item names. Skip it if you need a standalone inventory system, if your Homebox is older than v0.21, or if you cannot send photos of your possessions to a third-party model. Before committing, verify three things: that Homebox v0.21 or newer is running behind a URL the container can reach, that your API key works against gpt-5-mini, and that the ./homebox-companion-data volume survives a container restart, because settings.yaml is created there on first boot.

Frequently asked questions

Official sources

1. Duelion/homebox-companion on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases