Appearance
FAQ
Users & Access
How do I add a new user?
Go to Admin (top nav, visible to superusers only). Click the + button (Add User). Fill in the username, email, password, and permission flags (Active, Staff, Superuser). Click Save.
The new user can now log in at /login. If they need an owner record linked to their account, also go to Owners and create or edit an Owner, assigning the new user there.
How do I change or reset a user's password?
Superusers only. Go to Admin → click Edit next to the user → enter a new password in the Password and Confirm Password fields → Save. There is no self-service password reset; an administrator must do it.
How do I make a user a superuser?
Go to Admin → Edit next to the user → toggle Superuser to Yes → Save. The change takes effect on the user's next login (their current JWT will not have the new role until they refresh it).
What is the difference between a User and an Owner?
A User is a login account. An Owner is an inventory record that items and boxes can be attributed to. They are linked 1:1, but the link is optional — you can have a user with no owner record, or an owner with no linked user. Create the Owner in the Owners section and assign the user there.
Boxes
What is the difference between a Box ID and a Box Name?
Box ID is the unique physical identifier (max 50 characters) printed on the QR label and used by the scanner. It never changes.
Box Name is a human-readable label (e.g. "Christmas Decorations"). It is displayed instead of the Box ID only when the Display Name toggle is on.
How do I nest boxes inside other boxes?
When creating or editing a box, set the Parent Box field to another box. The child box then appears nested under the parent in the Box Management grid. Hierarchy counts propagate upward (the parent's "nested" columns count all descendants).
How do I move a box into a different parent box (reparent)?
Desktop: Go to Boxes → click Edit on the box → change the Parent Box field → Save.
Mobile: Use Mobile Reparent Boxes in the nav. Scan the new parent box first, then scan each child box you want to move under it. Tap Reparent N Boxes to apply.
What happens to items if I delete a box?
Items in a deleted box become unassigned — their box field is cleared and they remain in the system. Go to Items to find them (search for items without a box) and reassign them.
What happens to child boxes if I delete a parent box?
Cascade delete
Deleting a parent box also deletes all boxes nested inside it, at all levels. Items in those deleted child boxes also become unassigned. There is no undo. Move child boxes to a different parent before deleting if you want to keep them.
Why is a box showing "0% Processed"?
Processed = percentage of items in the box that have a name. 0% means all items are unnamed. Click Name Unnamed Items on that row to open the labeling view and give each item a name.
Photos & Items
My photo upload was skipped as a duplicate — why?
ItemChaos calculates an MD5 hash of each photo file before uploading. If an identical file (same hash) was already uploaded for that item, the upload is skipped automatically. This prevents the same photo appearing twice. If you want to replace the photo, delete the existing one from the item editor first.
How do I merge duplicate items?
Go to Items. Select two or more items using the checkboxes on their cards, then choose Merge from the action dropdown. The selected items are merged into one, combining their metadata. Only use this on true duplicates — the merge is not reversible through the UI.
What is a Key Photo, and how do I set it?
The Key Photo is the primary thumbnail shown on item cards. When you upload multiple photos to an item, you can open the item editor (/edit-item/:id) and mark one photo as the key photo. If no photo is marked as key, the first uploaded photo is used.
Can I undo a crop or revert to the original photo?
Yes. Open the item editor (/edit-item/:id) → find the photo → use Clear Crop (the revert action). This removes the saved cropped version and falls back to the original full-resolution photo.
What is the pan/zoom feature on photos?
Instead of (or in addition to) cropping, you can drag the photo in the item card to reposition how it is framed in the thumbnail. This is non-destructive — it stores offset percentages and a zoom scale, not a new image file. To reset, drag it back to center.
Financial Tracking
What financial fields are available per item?
Each item has three independent cost fields:
| Field | Meaning |
|---|---|
| Original Cost | What you paid when purchased |
| Current Value | Estimated market value today |
| Replacement Cost | What it would cost to buy the same item new today |
All three are optional. The Home page aggregates them across all items in the Financial Overview section.
Labels
How do I print box labels?
Go to Labels in the nav. Enter a Starting Number (the first box ID in the sequence) and the Number of Labels (automatically adjusted to an even number). Click Download Labels. A PDF downloads containing both box label sheets (4.25 × 11") and item log sheets with QR codes. Print box labels on adhesive label stock or plain paper with shipping tape.
Transfers
How do I transfer items to a new owner or box?
- Go to Transfers → Create New Transfer.
- Give the transfer a name and optionally set the destination box and new owner.
- Go to a box page (Boxes → View Items on a row) and assign items to the transfer template.
- On the transfer card, click View Items to confirm what's assigned.
- Click Download PDF to generate a transfer report.
- When done, mark the transfer Complete by editing the template.
AI Identification
What does the AI identification feature require?
A vision model server that your administrator runs on your own hardware (llama.cpp llama-server with a vision model, reached over the OpenAI-compatible API). As set up, photos go only to that server, not to a cloud AI service. Suggestions can take a minute or two. If the AI Identify page returns errors or empty suggestions, the model server is down, busy or unreachable — ask your administrator.
Why did AI only fill some fields on my item?
AI suggestions are non-destructive: they only populate fields that are currently empty. If a field already has a value, the AI suggestion for that field is ignored. This prevents AI from overwriting data you entered manually.