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. Use the AI Chat to manage your inventory, find locations, or update details just by asking.

🔄 How It Works

flowchart LR
    A[Connect to Homebox<br/>Configured key or legacy login] --> 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, tags/]
    

1. Connect – Enter directly with a configured Homebox API key, or use your existing Homebox credentials when no key is configured
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

Compatibility: Integration tests use Homebox v0.26.2. Homebox API keys require v0.26.0 or newer; retaining legacy login does not add support for older inventory APIs.

🚀 Quick Start

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
      - HBC_HOMEBOX_API_KEY=${HBC_HOMEBOX_API_KEY:-}
    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.

If Homebox runs in another Compose service, put both services on the same Docker network and use the Homebox service name, for example http://homebox:7745. localhost from inside the Companion container refers to the Companion container itself.

ARM64/Raspberry Pi: Docker images are built for both linux/amd64 and linux/arm64 architectures.

Homebox API key or legacy login

To enter Companion without a login screen, create a key in Homebox → Profile → API Keys and copy its one-time token. Set it on the Companion server:

HBC_HOMEBOX_URL=http://your-homebox-ip:7745
HBC_HOMEBOX_API_KEY=hb_your_homebox_issued_key

Restart Companion after changing these values. With Docker Compose, keep the explicit HBC_HOMEBOX_API_KEY environment entry shown above and run docker compose up -d --force-recreate. A Compose .env file supplies interpolation values; it does not automatically pass every variable into the container.

A configured key is used only by the server. The browser receives no Homebox key and has no login, session refresh or Homebox logout action. Missing, empty or whitespace-only keys preserve the username/password flow. An invalid, expired or revoked key shows a connection error with Retry; it never falls back to a password prompt. Removing the key and restarting restores legacy login.

All people who can reach a key-mode deployment act as the key's Homebox owner. Use a dedicated Homebox user with the intended collection permissions and control access through your network or reverse proxy. Browser chat contexts separate conversation history and pending approvals; they are not accounts or access credentials. Existing contextless chats and scan drafts remain stored, but are not loaded automatically into a newly verified context. Clearing browser data creates a new chat context. Server chat state remains in memory with its existing TTL and requires a single worker for consistent conversations.

To rotate a key, create a replacement in Homebox, update the server environment, restart Companion and verify its connection, then revoke the old key in Homebox. Companion does not refresh or revoke API keys. Homebox v0.26.x requires its own stable HBOX_AUTH_API_KEY_PEPPER of at least 32 bytes; configure that on Homebox, never on Companion. See Homebox configuration.

Shared settings

Authenticated Homebox users can manage shared settings, AI model profiles, custom fields and server logs without additional account configuration. In API-key mode, access uses the configured key's Homebox identity. Homebox credentials are revalidated when accessing Companion's local settings and logs.

When editing an AI profile, leave the API key blank to keep its saved key, including when changing the model or API base URL. A primary profile without a key uses the configured environment default; a fallback without a key inherits the primary key. Set a profile's own key when it needs different credentials.

✨ Features

AI-Powered Detection

• Identifies multiple items in a single photo
• Extracts manufacturer, model, serial number, price when visible
• Suggests tags from your existing Homebox tags
• 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 tag for all detected items
• Define custom Homebox fields with AI instructions (the AI populates them during detection)

Chat Assistant

• Natural language queries – Ask questions like "How many items do I have?" or "List my tags"
• Inventory actions – Create, update, move, or delete items through conversation
• Approval workflow – Review and approve AI-proposed changes before they're applied
• Streaming responses – Real-time AI responses with tool execution feedback

🤖 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.

Fallback Support: You can configure a secondary LLM profile in Settings that automatically activates if your primary provider fails.

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

Requests exceeding the body limit return HTTP 413, including chunked uploads. Missing or malformed legacy bearer credentials are rejected before multipart files are read. Configure matching body and concurrency limits on your reverse proxy to bound simultaneous uploads as well. If legitimate multi-image requests exceed 100 MiB, raise HBC_MAX_REQUEST_SIZE_MB deliberately; the per-file limit still applies.

HBC_IMAGE_QUALITY=high

# Allow only your frontend domain
HBC_CORS_ORIGINS=https://inventory.example.com

# Multiple origins (comma-separated)
HBC_CORS_ORIGINS=https://inventory.example.com,https://admin.example.com

💡 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, define custom fields, and manage LLM profiles without restarting.
• Long press to confirm all – On the review screen, long-press the confirm button to accept all remaining items at once.

Development

Target recovery contributions at dev. Changes on dev are not yet a release; promotion to main and publishing are separate steps.

Use Python 3.14+, Node 22, uv 0.9.17+ (CI and Docker use 0.12.5), and locked installs:

uv sync --locked
cd frontend
npm ci

The PR and dev CI workflow runs Python checks, frontend checks, mocked browser tests, and disposable Homebox integration tests. See tests/README.md for local commands and Docker/browser prerequisites. These suites require no paid LLM calls.

For a deliberate Python dependency refresh, run uv sync --upgrade --exclude-newer "30 days" with a uv version that supports relative durations (0.9.17+). This applies the cooldown only to that refresh; routine installs use the committed lockfile with uv sync --locked. For frontend updates, verify selected releases and transitive dependencies are at least 30 days old, update the lockfile, and rerun the checks and npm audit.

📄 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