# Project pack: HomeBox @ 1fd2882

Facts about **HomeBox** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and 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.

## Version and source
- Repository: https://github.com/sysadminsmedia/homebox
- Pinned commit: `1fd28822634a3d5935c002d569559ef46530d4a0`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/sysadminsmedia/homebox/archive/1fd28822634a3d5935c002d569559ef46530d4a0.zip
- 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.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```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
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```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
  ```

- Needs: 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
Read these in the repository before changing code: `.github/AGENTS.md`.

## Customisation points (settings → extend → code)
- **entity-types-and-templates** [settings]: Make your own kinds of thing, such as "Garage shelf", "Power tool" or "Kids' clothes box", each with pre-filled fields. → `Collection → Entity Types and Templates (frontend/pages/collection/index/entity-types.vue, frontend/pages/templates.vue)`
- **tags-and-custom-fields** [settings]: Group items your way (e.g. "insured", "lent out", "for sale") and add fields such as serial number or size. → `Tags page and custom fields on each item (frontend/pages/tags.vue)`
- **theme-and-language** [settings]: Pick a colour theme and the interface language for each person. → `Profile → theme picker (themes listed in frontend/lib/data/themes.ts); 40+ languages in frontend/locales/`
- **notifiers-and-maintenance** [extend]: Send maintenance reminders to Telegram, Discord, ntfy, email and many more services. → `Collection → Notifiers (frontend/pages/collection/index/notifiers.vue) plus maintenance schedules on each item`
- **labels-and-csv-import** [extend]: Print QR labels for boxes and shelves; bulk-add items from a spreadsheet. → `Label generator (frontend/pages/reports/label-generator.vue, backend/pkgs/labelmaker/); CSV import and export in Collection → Tools`
- **api** [extend]: Scripts, phone shortcuts and links to other home apps. → `REST API under /api/v1, with interactive docs at /swagger/ on your instance; API keys (backend/app/api/handlers/v1/v1_ctrl_api_keys.go)`
- **ui-pages** [code]: New screens, such as a moving-house checklist or an insurance summary. → `frontend/pages/**, frontend/components/** (shadcn-vue parts in frontend/components/ui/)`
- **backend** [code]: New data or behaviour. Every database change needs a migration for both SQLite and PostgreSQL. → `backend/app/api/handlers/v1/ (endpoints), backend/internal/data/repo/ (data access), backend/internal/data/ent/schema/ (models), backend/internal/data/migrations/sqlite3 and postgres`

## Must keep working
- Existing items, locations, photos and receipts. Back up the data folder before changing code.
- Collection permissions (members of one collection must not see another collection's items).
- Every database change needs migrations in both backend/internal/data/migrations/sqlite3 and postgres.
- Regenerate Swagger and TypeScript types (task swag, task typescript-types) after changing the API; don't hand-edit generated files.
- Keep HBOX_AUTH_API_KEY_PEPPER stable; changing it breaks every existing API key.

## Staying updatable
Entity types, templates, custom fields, notifiers, labels, CSV import and the API cover most household needs without a fork. For code changes, follow .github/AGENTS.md. Upstream does not accept AI-only pull requests (see CONTRIBUTING.md), so keep personal changes in your own copy unless you can explain and test every line yourself.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite database and uploaded files in the /data volume by default; PostgreSQL optional. Back up the whole data folder (database plus photos and receipts). A list of valuables with photos and prices is sensitive: it shows what a burglar would want. Use Collection → Tools to export before big changes.
- Service: Notification services (Discord, Telegram, ntfy, email, Pushover, webhooks and more, through Shoutrrr) (optional, free with most services): Maintenance reminders, for example "service the boiler" or "replace the smoke alarm battery".
- Service: Email (SMTP) (optional, free with most providers): Password-reset and other emails.
- Service: Meilisearch (optional, free (self-hosted)): Faster search for very large inventories. The built-in database search is enough for most homes.
- Setting `HBOX_AUTH_API_KEY_PEPPER` (**secret**: the person enters it themselves, never in chat): A long random secret (at least 32 bytes). The app will not start without it. Keep it the same across restarts. Never paste it into an AI chat.
- Setting `TZ`: Your time zone, so reminders arrive at the right time (e.g. Europe/London).
- Setting `HBOX_OPTIONS_ALLOW_REGISTRATION`: Defaults to true. Set to false once your household has its accounts, so strangers can't sign up.
- Setting `HBOX_WEB_MAX_UPLOAD_SIZE`: Largest photo or document you can upload, in MB (default 10).
- Setting `HBOX_OPTIONS_CURRENCY_CONFIG`: Optional JSON file that adds extra currencies.
- Setting `HBOX_LABEL_MAKER_WIDTH`: Width of printed labels in pixels. Similar HBOX_LABEL_MAKER_* variables set height, margin and padding.
- Set HBOX_OPTIONS_ALLOW_REGISTRATION=false after creating your accounts, and use HTTPS before exposing it to the internet.
- Your inventory shows what valuables you have and where. Keep it off the public internet if you can, and back it up.
- Notifier URLs can make HomeBox contact other machines on your network. The HBOX_NOTIFIER_* network settings in the docs limit this.

---

# Customising HomeBox

HomeBox has a Go backend and a Nuxt frontend, but **most household adaptations are settings**. Try levels 1 and 2 before touching code.

## Level 1: Settings (no code)
- **Kinds of thing:** Collection → Entity Types. Make types such as "Room", "Shelf", "Box" (tick "container") or "Power tool", "Appliance" (items). Give each a default template.
- **Templates:** the Templates page. Pre-fill fields such as manufacturer, warranty length or custom fields for each new item.
- **Tags and custom fields:** tag items "insured", "lent out" or "for sale"; add fields such as serial number, size or colour.
- **Theme and language:** Profile → theme picker (themes in `frontend/lib/data/themes.ts`) and language (40+ languages).
- **Members and invites:** Collection → Members / Invites, so the whole household shares one inventory.
- **Server options:** environment variables such as `HBOX_OPTIONS_ALLOW_REGISTRATION`, `HBOX_WEB_MAX_UPLOAD_SIZE` and `HBOX_LABEL_MAKER_*` (full list in the docs, Quick start → Configure).

## Level 2: Extend (no fork)
- **Notifiers** (Collection → Notifiers): Shoutrrr URLs for Telegram, Discord, ntfy, email, Pushover, generic webhooks and more. They fire for scheduled maintenance on items.
- **QR labels:** the label generator (`/reports/label-generator`) prints labels for boxes, shelves and items. Scan one to open its page.
- **CSV import and export** (Collection → Tools): bulk-add from a spreadsheet; use `HB.import_ref` to avoid duplicates.
- **REST API** under `/api/v1`, with interactive docs at `/swagger/` on your instance. Create an API key in your profile for scripts and phone shortcuts.

## Level 3: Code
Read upstream `.github/AGENTS.md` first. Note that the real data folder is `backend/internal/data/`.

| Change | Where |
|---|---|
| New page or view | `frontend/pages/**`, using components from `frontend/components/` (shadcn-vue parts in `frontend/components/ui/`) |
| Text | `frontend/locales/en.json` (other languages come from Weblate) |
| New endpoint | `backend/app/api/handlers/v1/v1_ctrl_*.go`, registered in `backend/app/api/routes.go` |
| Data access | `backend/internal/data/repo/` |
| New data | `backend/internal/data/ent/schema/` + a migration in **both** `backend/internal/data/migrations/sqlite3/` and `.../postgres/` |
| API types for the frontend | `task swag` then `task typescript-types` (generated; don't hand-edit) |

## Running locally
- **Just use it:** create a secret with `openssl rand -base64 48 > hbox.pepper`, then
  `docker run -d -p 3100:7745 -e HBOX_AUTH_API_KEY_PEPPER="$(cat hbox.pepper)" -v homebox-data:/data ghcr.io/sysadminsmedia/homebox:latest`.
  Open http://localhost:3100 and register.
- **Develop:**
  1. Install Go, Node.js, pnpm and Task (taskfile.dev).
  2. Run `task setup`.
  3. Start the backend with `task go:run` (it seeds demo data).
  4. Start the frontend with `task ui:dev`.
  5. Open http://localhost:3000.
- **Check:** `task go:test`, `task go:lint`, `task ui:check`, `task ui:fix`.

## Pitfalls
- Back up the data folder first. Photos and receipts live there next to the database.
- `HBOX_AUTH_API_KEY_PEPPER` is required and must not change, or existing API keys stop working.
- Forgetting the PostgreSQL migration (or the SQLite one) breaks the other database.
- Turn off open registration once your household has accounts.
- Upstream closes AI-only pull requests. Keep personal changes in your own copy.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/homebox/1fd2882/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/homebox/1fd2882/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/homebox/1fd2882/r2/SKILL.md)