The Problem
Home inventory management is typically handled with spreadsheets, notes, or memory. HomeBox solves the specific problem of tracking physical items—where they are, what they cost, when they need maintenance, and which documents or warranties apply to them—in a self-hosted, lightweight system that runs on modest hardware.
What This Does
HomeBox is a Go-based inventory and organization system for home users. The backend (backend/app/api/main.go) exposes a REST API with handlers for entities, attachments, maintenance, labels, QR codes, and reporting (backend/app/api/handlers/v1/). Data persistence uses SQLite via the Ent ORM (backend/internal/data/ent/), keeping deployment simple—no external database required.
The project includes Docker images in three variants: standard, rootless, and hardened (Dockerfile, Dockerfile.rootless, Dockerfile.hardened). CI/CD is handled through both GitHub Actions (.github/workflows/) and GitLab CI (.gitlab-ci.yml), with release binaries built via GoReleaser (backend/.goreleaser.yaml). The frontend is embedded in the Go binary, so a single container serves both UI and API.
How To Use It
Setup: Deploy via Docker using the documented command from the README:
mkdir -p /path/to/data/folder chown 65532:65532 -R /path/to/data/folder docker run -d \ --name homebox \ --restart unless-stopped \ --publish 3100:7745 \ --env TZ=Europe/Bucharest \ --volume /path/to/data/folder/:/data \ ghcr.io/sysadminsmedia/homebox:latest
Configuration: Environment variables control the data directory, timezone, and demo mode. The backend/app/api/setup.go file handles initial configuration. For non-Docker development, Taskfile.yml defines build tasks, and backend/go.mod manages Go module dependencies.
Running it: The container exposes port 7745 internally. Access the web UI at http://localhost:3100. The README documents a demo instance at https://demo.homebox.software for evaluation.
Real-World Use
A home lab operator or small business could deploy HomeBox to track IT equipment, tools, and appliances. For example, a user could register a laptop with purchase date, warranty document, maintenance schedule, and photos. The label maker endpoint (v1ctrllabelmaker.go) generates printable QR labels for physical asset tagging. The reporting service (backend/internal/core/services/reporting/) exports bill-of-materials data to CSV for insurance or tax purposes.
Code Health & Issues
Low - OpenAPI/Swagger docs are generated but appear static (backend/app/api/static/docs/); verify they stay in sync with handler changes. Low - The repo contains cosign.key and cosign.pub in backend/. If the private key is a signing key for releases, it should be held in CI secrets, not the repo. Low - Agent instruction files (.github/agents/, .github/instructions/) suggest AI-assisted development patterns; review generated code for consistency with project conventions. Positive - 15 test files exist, CI workflows cover backend, frontend, and E2E paths, and a license plus contribution guidelines are present. The codebase is well-structured with clear separation between API handlers, services, and data layers.
The Bottom Line
HomeBox is a mature, well-organized self-hosted inventory system with a clean Go backend, sensible Docker packaging, and active CI. It is well-suited for home users and small businesses that want a simple, single-binary deployment without infrastructure overhead. The primary caveats are the private key in the repo and the need to verify API documentation freshness.