# ============================================================================ # Homebox Companion - Environment Variables Reference # ============================================================================ # Copy this file to .env and fill in your values. # All variables use the HBC_ prefix to avoid conflicts with other apps. # # Settings managed by the UI use these values for their initial bootstrap. # Server connection/auth settings are read at startup; restart after changing them. # HBC_HOMEBOX_API_KEY is never stored in data/settings.yaml or sent to the browser. # ============================================================================ # REQUIRED SETTINGS # ============================================================================ # Your LLM API key # - For OpenAI: Get one at https://platform.openai.com/api-keys # - For OpenRouter: Get one at https://openrouter.ai/keys # - For Anthropic: Get one at https://console.anthropic.com/ HBC_LLM_API_KEY=sk-your-api-key-here # ============================================================================ # HOMEBOX CONNECTION # ============================================================================ # URL of your Homebox instance (default: local Homebox) # Examples: # - Local: http://localhost:7745 # - Local network: http://192.168.1.100:7745 # - Domain: https://homebox.example.com HBC_HOMEBOX_URL=http://localhost:7745 # Optional Homebox-issued API key (Homebox Profile -> API Keys). # A nonempty value enables direct entry without a Companion login screen. # Leave empty to retain Homebox username/password login, refresh and logout. # Invalid/expired keys show a connection error; they never fall back to login. # Everyone who can reach Companion acts as this key's Homebox owner. Control # deployment access through your network/reverse proxy. Restart after changes. # This is not your LLM key or Homebox's HBOX_AUTH_API_KEY_PEPPER. HBC_HOMEBOX_API_KEY= # Public URL for Homebox links in chat (default: same as HBC_HOMEBOX_URL) # Use when your API accesses Homebox internally but users access it via a public URL. # Example: API uses http://homebox:7745, users access https://homebox.example.com # HBC_LINK_BASE_URL=https://homebox.example.com # ============================================================================ # LLM CONFIGURATION # ============================================================================ # This app uses LiteLLM for multi-provider support. You can use OpenAI, # Anthropic, Google, OpenRouter, or any LiteLLM-compatible provider. # Model identifier (default: gpt-5-mini) # Examples: # OpenAI: gpt-5-mini, gpt-5-nano, gpt-4o, gpt-4o-mini # Anthropic: claude-3-5-sonnet-20241022, claude-3-opus-20240229 # Google: gemini-2.0-flash, gemini-1.5-pro # OpenRouter: openrouter/openai/gpt-5-mini, openrouter/anthropic/claude-3.5-sonnet HBC_LLM_MODEL=gpt-5-mini # Custom API base URL (optional) # Only needed for proxies, gateways, or OpenRouter # Examples: # OpenRouter: https://openrouter.ai/api/v1 # Custom: https://your-proxy.com/v1 # HBC_LLM_API_BASE= # Skip LiteLLM capability validation (default: false) # Set to true only if using a model that LiteLLM doesn't recognize # HBC_LLM_ALLOW_UNSAFE_MODELS=false # LLM request timeout in seconds (default: 120) # How long to wait for the LLM API to respond before giving up # HBC_LLM_TIMEOUT=120 # LLM streaming timeout in seconds (default: 300) # Longer timeout for streaming responses like hierarchical views with many items # HBC_LLM_STREAM_TIMEOUT=300 # ============================================================================ # LEGACY OPENAI VARIABLES (Deprecated - use HBC_LLM_* instead) # ============================================================================ # These still work but are deprecated. New deployments should use HBC_LLM_* variables. # HBC_OPENAI_API_KEY=sk-your-openai-api-key-here # HBC_OPENAI_MODEL=gpt-5-mini # ============================================================================ # IMAGE PROCESSING # ============================================================================ # Image quality for uploads to Homebox (default: medium) # Compression happens server-side during AI analysis to avoid slowing mobile devices. # Options: # raw - No compression, original files (largest file size) # high - 2560px max, 85% JPEG quality (best quality, moderate size) # medium - 1920px max, 75% JPEG quality (balanced - recommended) # low - 1280px max, 60% JPEG quality (smallest, faster uploads) HBC_IMAGE_QUALITY=medium # ============================================================================ # SERVER CONFIGURATION # ============================================================================ # Host to bind the web server to (default: 0.0.0.0) HBC_SERVER_HOST=0.0.0.0 # Port for the web server (default: 8000) HBC_SERVER_PORT=8000 # Logging level (default: INFO) # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL HBC_LOG_LEVEL=INFO # Disable GitHub update checks (default: false) # Set to true to skip version checks on startup HBC_DISABLE_UPDATE_CHECK=false # Maximum individual file upload size in MiB; must be positive (default: 20) HBC_MAX_UPLOAD_SIZE_MB=20 # Maximum aggregate API request body in MiB; must be positive (default: 100). # Includes all files and multipart overhead; larger requests return HTTP 413. # HBC_MAX_REQUEST_SIZE_MB=100 # CORS origins (default: *) # Comma-separated origins. In legacy mode, * permits any origin. # API-key mode uses same-origin requests unless explicit origins are listed; # * does not open cross-origin access in API-key mode. # Example: http://localhost:3000,https://example.com HBC_CORS_ORIGINS=* # ============================================================================ # CAPTURE LIMITS # ============================================================================ # Photos taken through this app are NOT saved to your device's photo gallery. # These limits minimize potential data loss if something goes wrong during a # capture session. Increase at your own risk. # Maximum images per capture session (default: 30) # HBC_CAPTURE_MAX_IMAGES=30 # Maximum file size per image in MB (default: 10) # HBC_CAPTURE_MAX_FILE_SIZE_MB=10 # ============================================================================ # RATE LIMITING (Optional) # ============================================================================ # Controls API request throttling to prevent hitting OpenAI rate limits. # Default settings are conservative (80% of Tier 1 limits). # Only configure if you have a higher-tier account or need to adjust limits. # Enable/disable rate limiting (default: true) # HBC_RATE_LIMIT_ENABLED=true # Requests per minute limit (default: 400, Tier 1 limit is 500) # HBC_RATE_LIMIT_RPM=400 # Tokens per minute limit (default: 400000, Tier 1 limit is 500000 for gpt-5-mini) # HBC_RATE_LIMIT_TPM=400000 # Burst capacity multiplier (default: 1.5, allows short bursts above the limit) # HBC_RATE_LIMIT_BURST_MULTIPLIER=1.5 # Examples for different OpenAI tiers: # Tier 2: HBC_RATE_LIMIT_RPM=4000 HBC_RATE_LIMIT_TPM=1600000 # Tier 3: HBC_RATE_LIMIT_RPM=4000 HBC_RATE_LIMIT_TPM=3200000 # Auth rate limiting (brute-force protection) # Maximum login attempts per minute per IP address (default: 10) # Set to 0 to disable auth rate limiting # HBC_AUTH_RATE_LIMIT_RPM=10 # Chat rate limiting (LLM cost / abuse protection) # Maximum chat messages per minute per IP address (default: 20) # Set to 0 to disable chat rate limiting # HBC_CHAT_RATE_LIMIT_RPM=20 # ============================================================================ # LABEL PRINTING (Optional) # ============================================================================ # Enable a "Print Label" button in the UI after items are created. # This triggers Homebox's built-in labelmaker, which requires # HBOX_LABEL_MAKER_PRINT_COMMAND to be configured on your Homebox server. # See Homebox docs for configuring the print command. # Enable server-side label printing (default: false) # HBC_PRINT_ENABLED=false # ============================================================================ # AI OUTPUT CUSTOMIZATION (Optional) # ============================================================================ # These settings control how the AI formats detected item data. # Leave commented to use defaults, or customize via the Settings page in the UI. # NOTE: Settings page values take priority over these env vars. # Language for AI output (default: English) # HBC_AI_OUTPUT_LANGUAGE=English # Default tag ID to auto-apply to all detected items # Find tag IDs in your Homebox instance # HBC_AI_DEFAULT_TAG_ID= # Item naming format (default: [Type] [Brand] [Model] [Specs]) # HBC_AI_NAME=[Type] [Brand] [Model] [Specs], Title Case, item type first for searchability # Naming examples to guide the AI # HBC_AI_NAMING_EXAMPLES="Ball Bearing 6900-2RS 10x22x6mm", "Acrylic Paint Vallejo Game Color Bone White", "LED Strip COB Green 5V 1M" # Description format (default: condition/attributes only) # HBC_AI_DESCRIPTION=Condition/attributes only, max 1000 chars, NEVER mention quantity # Quantity counting rules (default: count identical together) # HBC_AI_QUANTITY=Count identical items together, separate different variants # Manufacturer extraction rules (default: only when visible) # HBC_AI_MANUFACTURER=Only when brand/logo is VISIBLE. Include recognizable brands only. # Model number extraction rules (default: only when visible) # HBC_AI_MODEL_NUMBER=Only when model/part number TEXT is clearly visible on label # Serial number extraction rules (default: only when visible) # HBC_AI_SERIAL_NUMBER=Only when S/N text is visible on sticker/label/engraving # Purchase price extraction rules (default: only from visible tags) # HBC_AI_PURCHASE_PRICE=Only from visible price tag/receipt. Just the number. # Purchase from extraction rules (default: only from visible packaging) # HBC_AI_PURCHASE_FROM=Only from visible packaging/receipt or user-specified # Notes format (default: only for defects/damage) # HBC_AI_NOTES=ONLY for defects/damage/warnings - leave null for normal items. GOOD: "Cracked lens", "Missing screws" | BAD: "Appears new", "Made in China"