Homebox Companion

Not affiliated with the Homebox project. This is an unofficial third-party companion app.

AI-powered companion for Homebox inventory management.

Take a photo of your stuff, and let AI identify and catalog items directly into your Homebox instance. Perfect for quickly inventorying a room, shelf, or collection.

🔄 How It Works

flowchart LR
    A[🔐 Login<br/>Homebox] --> B[📍 Select<br/>Location]
    B --> C[📸 Capture<br/>Photos]
    C --> D[✏️ Review &<br/>Edit Items]
    D --> E[✅ Submit to<br/>Homebox]
    
    B -.-> B1[/Browse, search,<br/>or scan QR/]
    C -.-> C1[/AI analyzes with<br/>OpenAI GPT-5/]
    D -.-> D1[/Edit names,<br/>quantities, labels/]
    

1. Login – Authenticate with your existing Homebox credentials
2. Select Location – Browse the location tree, search, or scan a Homebox QR code
3. Capture Photos – Take or upload photos of items (supports multiple photos per item)
4. AI Detection – AI vision (via LiteLLM*) identifies items, quantities, and metadata
5. Review & Edit – Adjust AI suggestions or ask AI to correct mistakes
6. Submit – Items are created in your Homebox inventory with photos attached

*LiteLLM is a Python adaptor library we use to call OpenAI directly, no Local AI model required (unless you want to), just your API key.

💰 OpenAI Cost Estimates

GPT-5 mini (default) offers the best accuracy. GPT-5 nano is 3x cheaper but may need more corrections. Typical cost: ~$0.30 per 100 items (mini) or ~$0.10 per 100 items (nano).

Prices as of 2025-12-10, using OpenAI’s published pricing for GPT-5 mini and GPT-5 nano.

📋 Requirements

Before you start, you'll need:

• An OpenAI API key – Get one at platform.openai.com
• A Homebox instance – Your own Homebox server, or use the demo server to test

Compatibility: Tested with Homebox v0.21+. Earlier versions may have different authentication behavior.

🚀 Quick Start

Try with Demo Server

Want to try it out without setting up Homebox? Use the public demo server:

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 login with [email protected] / demo

Docker (Recommended)

# docker-compose.yml
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://your-homebox-ip:7745
    ports:
      - 8000:8000

docker compose up -d

Open http://localhost:8000 in your browser.

Tip: If Homebox runs on the same machine but outside Docker, use http://host.docker.internal:PORT as the URL.

✨ Features

AI-Powered Detection

• Identifies multiple items in a single photo
• Extracts manufacturer, model, serial number, price when visible
• Suggests labels from your existing Homebox labels
• Multi-language support

Smart Workflow

• Multi-image analysis – Take photos from multiple angles for better accuracy
• Single-item mode – Force AI to treat a photo as one item (for sets/kits)
• AI corrections – Tell the AI what it got wrong and it re-analyzes
• Custom thumbnails – Crop and select the best image for each item

Location Management

• Browse hierarchical location tree
• Search locations by name
• Scan Homebox QR codes
• Create new locations on the fly

Customization

• Configure how AI formats each field (name style, description format, etc.)
• Set a default label for all detected items
• Export settings as environment variables for Docker persistence

🤖 LLM Provider Support

Homebox Companion uses LiteLLM as a Python library to call AI providers. You don't need to self-host anything – just get an OpenAI API key from platform.openai.com and you're ready to go. We officially support and test with OpenAI GPT models only.

HBC_LLM_API_KEY=any-value-works-for-local  # Just needs to be non-empty
HBC_LLM_API_BASE=http://localhost:11434     # Your local server URL
HBC_LLM_MODEL=ollama/llava:34b              # Your local model name
HBC_LLM_ALLOW_UNSAFE_MODELS=true            # Required for most local models

⚙️ Configuration

📝 Full reference: See .env.example for all available environment variables with detailed explanations and examples.

Essential Settings

For a quick setup, you only need to provide your OpenAI API key. All other settings have sensible defaults.

Advanced Settings

HBC_IMAGE_QUALITY=high

💡 Tips

• Batch more items for faster uploads – Images are analyzed by AI in parallel (up to 30 simultaneously), so adding more items actually feels faster than one at a time.
• Include receipts in your photos – AI can extract purchase price, retailer, and date from receipt images.
• Multiple angles = better results – Include close-ups of labels, serial numbers, or barcodes for more accurate detection.
• HTTPS required for QR scanning – Native camera QR detection only works over HTTPS. On HTTP, a "Take Photo" fallback is available.
• Use the Settings page – Customize AI behavior without restarting, then export settings as environment variables for Docker.
• Long press to confirm all – On the review screen, long-press the confirm button to accept all remaining items at once.

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Homebox – The inventory system this app extends
• OpenAI – Vision AI capabilities (GPT models)
• LiteLLM – LLM provider abstraction layer
• FastAPI & SvelteKit – Backend & frontend frameworks