HomeBox: a self-hosted home inventory system in a single Go container

What HomeBox is for, and who it is not for

HomeBox is an inventory and organization system built for the home user. The README frames the design around three principles: simple but expandable, written in Go for low resource use, and portable through SQLite plus an embedded web UI. The stated idle memory figure is under 50MB for the whole container. The feature list is concrete: items grouped into categories, locations and tags, custom fields per item, search, image upload, document and warranty tracking, and purchase and maintenance dates.

The intended user is someone cataloguing possessions at home. Insurance documentation, warranty expiry, and finding which box in the basement holds a specific cable are the obvious jobs. It is not a CMDB, not an asset system for a company with approval workflows, and not a barcode-first warehouse tool. The README does not describe multi-tenant roles, audit logs, or an approval chain, so anyone shopping for those should look elsewhere. This fork is maintained under the sysadminsmedia organization and credits the original project by @hay-kot, so it is a continuation rather than a fresh codebase.

How the Go backend, SQLite store and embedded UI fit together

The repository layout separates backend/ (Go) from frontend/. The Dockerfile builds the frontend first with Node 22 and pnpm 10, running pnpm build to produce a Nuxt output, then copies the compiled assets into the Go build under ./app/api/static/public. The Go stage compiles the API server, and the resulting binary serves both the JSON API and the static web interface from one process. That is why there is no separate web server to configure and no reverse proxy requirement for a basic install.

Persistence is SQLite, which is what makes the single-volume backup story work. Everything the application knows lives under /data in the container. The image exposes port 7745 internally; the README's run command maps host port 3100 to it. Authentication uses an API key pepper supplied through HBOX_AUTH_API_KEY_PEPPER, and the README instructs you to generate it with openssl rand -base64 48 and store it in a local file with restrictive permissions. The compose file in the repository shows HBOX_LOG_LEVEL and the same pepper variable, which confirms the environment-variable configuration surface. Three image variants are published: the default, latest-rootless, and latest-h (hardened).

Installing HomeBox with Docker and taking a first inventory

The README points to the configuration and Docker Compose page for full setup. The commands below are the ones the README itself gives. First, generate the pepper and write it to a file, then create the data directory. The chown matters because the rootless and hardened images run as a non-root user, and the README explicitly notes the permission requirement.

openssl rand -base64 48 > hbox.pepper
chmod 400 hbox.pepper
mkdir -p /path/to/data/folder
chown 65532:65532 -R /path/to/data/folder

With the pepper file in place, start the container. The pepper is passed by reading the file inline, the data directory is mounted at /data, and host port 3100 forwards to the container's 7745. Substitute your own timezone value for TZ.

docker run -d \
  --name homebox \
  --restart unless-stopped \
  --publish 3100:7745 \
  --env TZ=Europe/Bucharest \
  --env HBOX_AUTH_API_KEY_PEPPER=$(cat hbox.pepper) \
  --volume /path/to/data/folder/:/data \
  ghcr.io/sysadminsmedia/homebox:latest

After the container reports healthy, open http://localhost:3100 in a browser. You should see the embedded web UI served by the Go process, not a separate frontend server. Create the first item, assign it a location and a category, and attach an image to confirm that uploads are landing in the mounted volume. The README also lists latest-rootless and latest-h as alternative image tags if you want the non-root or hardened build; if you switch, re-check the ownership of the data directory. The project runs public demo and nightly instances at demo.homebox.software and nightly.homebox.software, which is the fastest way to look at the interface before you deploy anything.

Where HomeBox stops being the right tool

The design choices that make HomeBox easy to run are the same ones that bound it. SQLite and a single container mean there is no built-in replication, no shared database for multiple application nodes, and no documented horizontal scaling path. If two people in one household edit the same item at once, the README says nothing about conflict resolution, and with a single SQLite file there is no second writer to arbitrate.

Access control is the sharper limitation. The README documents an API key pepper for authentication but does not describe per-user roles, scoped permissions, or a guest view. For a household where everyone is trusted, that is fine. For a landlord tracking tenant deposits, or a small business where a contractor should see one category and not the rest, it is the wrong shape. The README also does not document rollback or downgrade steps, so pinning an image tag before an upgrade is the only safe habit the README supports. Finally, the search results around Homebox include unrelated businesses with similar names, so searching for help can surface logistics and energy companies rather than this project. The project's own docs site and Discord are the reliable channels.

HomeBox against a plain spreadsheet or a notes app

The realistic alternative for most people is not another inventory server. It is a spreadsheet, or a notes app with photos. The difference in approach is structural rather than cosmetic. A spreadsheet stores rows you define yourself; HomeBox stores items with a fixed schema of categories, locations, tags, custom fields, images, purchase and maintenance dates, and documents. That schema is what makes search and filtering work without you maintaining formulas, and it is also what makes migration out of HomeBox a data export problem rather than a copy-paste problem.

A notes app wins on speed of entry and loses on querying: you can write a note about a drill in seconds, but you cannot ask which items are in the garage and still under warranty without reading every note. HomeBox wins exactly there. The trade is that you must decide on a category and location taxonomy up front, or you will end up with both Garage and garage as separate locations. Neither option gives you an official mobile app: the README describes a responsive web design that works on phones and tablets, and does not mention a native Android or iOS client, so the browser is the interface.

Licence, upgrades and the cost of keeping it running

HomeBox is licensed under AGPL-3.0, and the LICENSE file sits at the repository root. If you run it privately for your household, the network-copyleft obligation is unlikely to touch you. If you modify it and expose the modified version to users over a network, the AGPL's source-availability condition applies to your modified version. This is a description of the licence text, not legal advice; read LICENSE and consult a lawyer if you plan to build a service on top of it.

The upgrade cost is low but not zero. Releases are tagged, and the repository shows v0.26.0, v0.26.1 and v0.26.2 clustered on 2026-06-13 and 2026-06-14, with the last push to the repository on 2026-06-14. That is more than six months before today, so this is not a project to describe as under active development at the moment; the honest statement is that the most recent push was on 2026-06-14. Upgrading means pulling a new image tag and restarting the container, with the SQLite file in /data as the thing you must back up first. Because the README does not document a downgrade procedure, keep a copy of the previous image tag and a pre-upgrade snapshot of /data before you move. The container itself is cheap to run; the pepper file and the data volume are the two pieces you must not lose.

Editorial conclusion

Adopt HomeBox if you want a private inventory database on your own hardware and you are comfortable running one container plus a volume backup. Skip it if you need multi-tenant access control, an official mobile app, or a hosted service, none of which the README describes. Before committing your data, verify that the pepper you generated is stored outside the container, that /data is writable by the image's user, and that the tags you plan to run still exist on ghcr.io.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes