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 – OpenAI vision identifies items, quantities, and metadata
5. Review & Edit – Adjust AI suggestions, merge items, or ask AI to correct mistakes
6. Submit – Items are created in your Homebox inventory with photos attached

https://github.com/user-attachments/assets/fcaae316-f4fa-462e-8ed2-d0d7e82145fd

💰 OpenAI Cost Estimates

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

Per-token pricing (per 1M tokens):

• GPT-5 nano

  • Input: $0.0500 / 1M tokens
  • Output: $0.4000 / 1M tokens

• GPT-5 mini

  • Input: $0.2500 / 1M tokens
  • Output: $2.0000 / 1M tokens

All estimates below are based on measured token usage from this app’s production prompt with 1–5 images per call.

Estimated API cost for Homebox Companion

GPT-5 mini

GPT-5 nano

Although gpt-5-nano may be smaller and faster on a per-token basis, our testing shows that it generates significantly more tokens to complete the same task, ultimately offsetting any apparent speed advantage.

📋 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

🚀 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_OPENAI_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_OPENAI_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.

Run from Source

Alternative to Docker if you prefer running directly on your system.

Prerequisites: Python 3.12+, Node.js 20+, uv

Linux / macOS

# Clone and install
git clone https://github.com/Duelion/homebox-companion.git
cd homebox-companion
uv sync

# Build frontend
cd frontend && npm install && npm run build && cd ..
mkdir -p server/static && cp -r frontend/build/* server/static/

# Configure - copy example and edit
cp .env.example .env
# Edit .env and set your HBC_OPENAI_API_KEY

# Run
uv run python -m server.app

Windows (PowerShell)

# Clone and install
git clone https://github.com/Duelion/homebox-companion.git
cd homebox-companion
uv sync

# Build frontend
cd frontend
npm install
npm run build
cd ..

# Copy frontend build to server static
New-Item -ItemType Directory -Force -Path server\static
Copy-Item -Path frontend\build\* -Destination server\static\ -Recurse -Force

# Configure - copy example and edit
Copy-Item .env.example .env
# Edit .env and set your HBC_OPENAI_API_KEY

# Run
uv run python -m server.app

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

Note: See .env.example for all available configuration options including AI customization settings.

✨ 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

⚙️ Configuration

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

Essential Settings

Advanced Settings

HBC_IMAGE_QUALITY=high

💡 Tips

• HTTPS recommended for QR scanning – Native camera QR detection only works over HTTPS. On HTTP, a "Take Photo" fallback is available.
• Multiple photos = better results – Include close-ups of labels, serial numbers, or receipts for more accurate detection.

📄 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
• FastAPI & SvelteKit – Backend & frontend frameworks