# Project pack: HomeBox @ 1fd2882

Facts about **HomeBox** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> HomeBox is a home inventory. Record the things you own, with photos, receipts, prices and warranty dates, and say where each one lives: which room, shelf or box. Search finds anything in seconds, and printable QR labels help you find what is inside a box without opening it. It runs on your own computer or server, so the list of what you own stays private.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://homebox.software/en/
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/sysadminsmedia/homebox
- Pinned commit: `1fd28822634a3d5935c002d569559ef46530d4a0`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/sysadminsmedia/homebox/archive/1fd28822634a3d5935c002d569559ef46530d4a0.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://homebox.software/en/
- Live demo: https://demo.homebox.software. Public demo run by the HomeBox team. Don't enter anything private.
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (not just your own household), you must offer them your source code under the same licence. Private household use has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/sysadminsmedia/homebox bespoke-homebox
  cd bespoke-homebox
  git checkout --detach 1fd28822634a3d5935c002d569559ef46530d4a0
  # Prepare development requirements and local configuration first.
  # Setup notes: backend on :7745 with demo data; in another terminal: task ui:dev (frontend on :3000)
  task setup && task go:run
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  openssl rand -base64 48 > hbox.pepper && docker run -d --name homebox --restart unless-stopped -p 3100:7745 -e TZ=Europe/London -e HBOX_AUTH_API_KEY_PEPPER="$(cat hbox.pepper)" -v homebox-data:/data ghcr.io/sysadminsmedia/homebox:latest # then open http://localhost:3100 and register the first account
  ```
- Tools these commands use: Docker, or for development Go + Node.js + pnpm + Task (taskfile.dev)
- Develop: `task setup && task go:run   # backend on :7745 with demo data; in another terminal: task ui:dev (frontend on :3000)`
- Test: `task go:test`
- Check/lint: `task go:lint && task ui:check && task ui:fix`
- Stack: go, typescript, vue (chi, ent, Nuxt 4, Vue 3, Tailwind CSS, shadcn-vue). Difficulty for a non-developer with an AI: **moderate**. Entity types, templates, custom fields, tags, notifiers and labels are settings. Code changes touch a Go backend and a Nuxt frontend, with Swagger and TypeScript types generated between them (task swag, task typescript-types).
- The project's own AI instructions, in the repository: `.github/AGENTS.md`.
Personal data: **yes**. Stored in: SQLite database and uploaded files in the /data volume by default; PostgreSQL optional. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/homebox/1fd2882/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/homebox/1fd2882/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/homebox/1fd2882/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/homebox/1fd2882/r3/SKILL.md)