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 upda
What is 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.
Overview of homebox-companion
What it is
Homebox Companion is an unofficial third-party AI-powered companion app for Homebox inventory management. It is not affiliated with the Homebox project. The app allows users to take photos of items and let AI identify and catalog them directly into a Homebox instance. It also includes an AI Chat feature to manage inventory, find locations, or update details by asking natural language questions.
Key features
- AI-Powered Detection: Identifies multiple items in a single photo, extracts manufacturer, model, serial number, and price when visible, suggests tags from existing Homebox tags, and supports multiple languages.
- Smart Workflow: Supports multi-image analysis from different angles, single-item mode for sets/kits, AI corrections via re-analysis, and custom thumbnail cropping.
- Location Management: Browse hierarchical location tree, search by name, scan Homebox QR codes, create new locations on the fly, and keep parent containers and physical locations separate on Homebox 0.27+.
- Customization: Configure how AI formats each field (name style, description format), set a default tag for all detected items, and define custom Homebox fields with AI instructions.
- Chat Assistant: Natural language queries (e.g., “How many items do I have?”), inventory actions (create, update, move, delete), approval workflow for AI-proposed changes, streaming responses, and access to 24 tools for interacting with the inventory.
Use cases
Quickly inventory a room, shelf, or collection by taking photos. Use the AI Chat to organize, search, and update inventory without manual data entry. Ideal for users who want to automate cataloging of household items, tools, or collectibles into a Homebox instance.
Getting started
Requirements: an OpenAI API key, a compatible Homebox instance, and a modern browser (Safari 16.4+, Chrome/Edge 111+, or Firefox 128+).Docker (recommended):# docker-compose.ymlservices: 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://your-homebox-ip:7745 - HBC_HOMEBOX_API_KEY=${HBC_HOMEBOX_API_KEY:-} - HBC_LLM_TIMEOUT=${HBC_LLM_TIMEOUT:-120} - HBC_AI_REQUEST_TIMEOUT=${HBC_AI_REQUEST_TIMEOUT:-} ports:
- 8000:8000 volumes:
- companion-data:/app/datavolumes: companion-data:docker compose up -dOpen http://localhost:8000 in your browser. For detailed configuration (API key setup, persistent settings, etc.), see the repository README.
License and pricing
License: GPL-3.0. Pricing: open source (free).
Based on the project's public README and repository metadata.