You bought a new router eighteen months ago, and now it's flaking out. Is it still under warranty? Where's the receipt? Which bin did you toss the original box in before it went to the garage? If you've ever dug through a shoebox of paper receipts or scrolled back through years of email confirmations looking for one answer, you already understand the problem Homebox solves. It's a self-hosted app for tracking what you own: what it is, where it lives, what it cost, and when the warranty runs out.
This guide walks through installing Homebox in its own LXC container on Proxmox VE, creating your first inventory, and getting a feel for locations, labels, and item tracking. The whole install takes about ten minutes, most of which is Proxmox downloading a container template in the background.
What You Will Learn
- What Homebox actually does and who it's useful for
- How to deploy it in an LXC container using the community-scripts helper
- How to create your account and set up your first location and item
- Where its files live inside the container, in case you ever need to poke around
- Common errors people run into during setup, and how to fix them
- A few habits worth adopting before your inventory grows past a handful of items
What Is This Feature?
Homebox is an open-source inventory tracker built specifically for household use rather than warehouses or retail. You create locations (garage, attic, office closet, storage unit), then add items to those locations with details like purchase date, price, serial number, and photos. Each item can carry custom fields and tags, so you can track warranty expiration on electronics one week and rental gear you loaned to a friend the next.
It's written in Go and uses SQLite for storage, which is a lightweight, file-based database that doesn't need a separate database server running alongside it. That's part of why it fits so comfortably in a small LXC container — a lightweight form of virtualization that shares the host's Linux kernel instead of emulating its own hardware the way a full VM does. Containers boot in a couple of seconds and use a fraction of the RAM a VM would need, which suits a small app like this one that mostly just sits there waiting for you to log an item.
There's no cloud account, no subscription, and no data leaving your network. Everything you enter stays on the disk of the container you create.
One feature worth knowing about up front: Homebox can generate printable labels with a unique QR code for each item or location, sized to fit standard Avery 5260 label sheets. Stick one on a storage bin, scan it with your phone later, and you're looking at exactly what's inside without opening the lid. It's a small feature, but it's the one that turns "I have an inventory app" into "I actually use my inventory app."
Why Would You Use It?
Plenty of people track possessions in a spreadsheet, and for a dozen items that's fine. It stops being fine once you're trying to remember which drawer the spare Ethernet cables are in, or proving to an insurance adjuster what was actually in the flooded basement.
A few situations where this pays off:
- Insurance claims. Photos, purchase prices, and serial numbers in one place make a claim after a fire, flood, or theft dramatically less painful to file.
- Warranty tracking. Homebox can flag items with an expiring warranty, so you're not digging through email six months after the return window closed.
- Shared or lent items. If you're the person in the family who lends out tools, camping gear, or the good ladder, a location field labeled "loaned to Dave" beats trying to remember months later.
Honestly, if you own fewer than twenty things worth tracking, you probably don't need this. But once you've got a garage, an attic, and a storage unit full of stuff you can't quite picture on demand, a proper inventory tool with search and photos earns its keep fast.
A spreadsheet can technically do some of this too, so it's worth being clear about where each one actually holds up:
| Task | Spreadsheet | Homebox |
|---|---|---|
| Attach a photo to an item | Awkward at best | Built in, one click |
| Print a scannable label for a bin | Not without a separate tool | Built in, QR code included |
| Search across thousands of items instantly | Slows down fast | Fast, indexed search |
| Flag items with an expiring warranty | Manual formulas, easy to break | Built in |
| Access from your phone while standing in the garage | Clunky | Responsive web page |
Prerequisites
Before you start, make sure you have:
- A working Proxmox VE host — this was tested on 8.x and 9.2, and the install process is identical on both.
- Root or admin access to the Proxmox VE web interface, and access to the node's shell (Datacenter → your node → Shell).
- At least 4 GB of free space on the storage you plan to use for the container's disk.
- Internet access from the Proxmox host, since the install script pulls files from GitHub and Debian's package repositories.
- About ten minutes and a browser to log in from once the container is up.
No domain name is required to get going. You'll want one later if you plan to reach Homebox from outside your home network, but a local IP address is fine while you're setting it up.
Step-by-Step Tutorial
1. Open the Proxmox VE shell
Log into the web interface, click your node in the left-hand tree, and choose Shell from the top-right menu. This puts you in a root shell on the Proxmox host itself, not inside a container yet.
2. Run the community-scripts installer
Paste this command and press enter:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/homebox.sh)"This runs a setup script maintained by the community-scripts project, the group that carries on the well-known collection of Proxmox helper scripts. It builds a fresh Debian 13 LXC container, installs Homebox inside it, and starts the service, without you needing to touch an installer ISO or download a container template by hand.
The script will ask whether you want Default or Advanced settings. Default is fine for most people and gives the container 1 CPU core, 1024 MB of RAM, and a 4 GB disk, running as an unprivileged container. Pick Advanced only if you want a static IP right away or need to change the hostname or storage target; otherwise the container gets an address from DHCP automatically.
3. Find the container's IP address
When the script finishes, it prints the new container's ID and IP address right there in the shell. If you scrolled past it, click the new container in the left tree and check the Summary tab, where the IP address is listed under the network section.
4. Confirm the service is running
Open the container's Console and log in as root using the password the script printed at the end of installation. Then check the service:
systemctl status homeboxYou want to see active (running) in green. If it's there, Homebox is already listening on port 7745 and you can reach it from any browser on your network.
5. Open Homebox in your browser
Go to http://<container-ip>:7745. You'll land on a login screen with a link to register a new account. There's no default username and password to remember here — you create the first (and only, unless you invite others) account yourself the moment you visit the site.
6. Create your account and first location
Register with an email address and password — nothing gets emailed anywhere, this just becomes your login. Once you're in, click Locations and add one, something like "Garage" or "Office." Locations can be nested, so "Garage → Shelf 3" works too if you want that level of detail later.
7. Add your first item
Click Items → Create, give it a name, assign it to the location you just made, and fill in whatever fields matter to you: purchase price, purchase date, serial number, and a photo if you have one handy. None of the fields beyond the name are required, so you can start rough and fill in details over time as you go through boxes.
Commands Explained
| Command | What it does |
|---|---|
systemctl status homebox | Shows whether the Homebox service is running and prints its most recent log lines. |
systemctl restart homebox | Restarts the service after you change /opt/homebox/.env — the app won't pick up config changes until you do this. |
cat /opt/homebox/.env | Shows the environment file the installer created, including the port, bind address, and the randomly generated authentication key. |
journalctl -u homebox -f | Tails the service's log in real time, useful for watching what happens during login attempts or file uploads. |
pct status <container-id> | Run from the Proxmox host, this confirms whether the container itself is actually running. |
Common Errors
Browser shows "connection refused" at the container's IP — this almost always means you left off the port. Homebox doesn't run on port 80, so http://192.168.1.50 won't work, but http://192.168.1.50:7745 will. Double-check you typed the port.
Container has no IP address after install — this usually points to the network bridge you picked during setup, commonly vmbr0, not having DHCP available on that segment. Check the container's Hardware → Network Device settings and confirm it's using the same bridge your other VMs and containers get addresses on successfully.
Registration page never loads, spinner just sits there — check that the homebox service actually started with systemctl status homebox. If it's not active, the console log from the last boot (visible with journalctl -u homebox) usually names a port conflict or a permissions problem with /opt/homebox.
Troubleshooting
If the app loads but behaves oddly, start with the logs:
journalctl -u homebox -fLeave that running, then reproduce whatever's going wrong — a failed upload, a login that won't stick, whatever it is. The error usually shows up in the log the moment it happens.
If the container is unreachable entirely, confirm it's up from the Proxmox host itself:
pct status <container-id>A status of stopped means the container isn't running at all; start it from the Proxmox web UI or with pct start <container-id>. If it says running but you still can't connect, the problem is almost always the network bridge or a firewall rule on the container or the host blocking port 7745.
And if you edited /opt/homebox/.env and the service won't come back up at all, check for a stray typo — a missing equals sign or an accidentally deleted HBOX_AUTH_API_KEY_PEPPER line will stop it from starting cleanly. Restore the value or re-run the community-scripts installer's update option to regenerate the container.
Best Practices
- Take a Proxmox snapshot of the container right after your first successful login, before you've entered any real data. It's a cheap rollback point if something goes wrong later.
- Back up the container regularly with vzdump or Proxmox Backup Server. All your inventory data lives inside this one container, so treat it like anything else you'd hate to lose.
- Put a reverse proxy with HTTPS in front of Homebox if you want to reach it from outside your home network. Uploading photos of your possessions over plain HTTP across the internet isn't something you want to do.
- Don't bother with elaborate tagging schemes on day one. Add a handful of locations, get a feel for how you actually search for things, then expand your labels and custom fields once you know what you'll actually use.
- Once you've got a few dozen items logged, generate a batch of QR labels from the tools page and actually stick them on bins. An inventory app you never print labels for tends to quietly stop getting updated after a month.
- Re-run the community-scripts installer periodically to update to newer Homebox releases — it detects the existing container instead of creating a second one.
Frequently Asked Questions
Is Homebox free?
Yes. It's open source, and self-hosting it costs you nothing beyond the small amount of CPU, RAM, and disk the container uses.
Can multiple people in my household use it?
Yes, you can register additional accounts from the same instance, and everyone shares the same inventory unless you set up separate item ownership within Homebox itself.
Does it work on my phone?
The web interface is responsive and works fine in a mobile browser. There's no dedicated mobile app, but bookmarking the page or adding it to your home screen gets you most of the way there.
What happens if the container's disk fails?
You lose your inventory unless you've been backing it up, which is exactly why regular vzdump or Proxmox Backup Server backups matter here more than they might for a throwaway test container.
Can I import items from a spreadsheet?
Homebox supports CSV import and export from within the app, so if you've already got a spreadsheet of possessions, you don't have to re-enter everything by hand.
Conclusion
You've now got a working inventory system running on hardware you already own, with no subscription and no data leaving your network. Start small: log the expensive stuff first, the things you'd actually file an insurance claim over, and expand from there as you go through closets and storage bins. The receipt-hunting problem this solves only gets more annoying the longer you put off setting something like this up, and now that part's done.