Box Manifest is a self-hosted physical inventory system built around one universal hierarchy. Locations, containers, and items are represented by the same kind of node, so any node can contain other nodes.

This repository currently contains:

A Go HTTP server backed by SQLite
A native Android client built with Kotlin and Jetpack Compose
A Vite, React, and TypeScript web client
A JSON-first command-line client for people, scripts, and AI agents
An OpenAPI 3.1 contract

The project is pre-release and has no compatibility guarantee yet.

Current behavior

Arbitrarily deep node hierarchy
Optional non-negative integer quantities
Single and bulk node creation
Atomic single and multi-node moves
Empty-only deletion
Hierarchy search and breadcrumbs on Android and web
Android offline browsing, creation, and editing with automatic queued sync
JSON tree-import preview and atomic commit
Stable six-character lookup codes
QR-label preview/export on both clients, with scanning and visual Find on Android

See the universal-tree decision for the core model and the project plan for current boundaries and near-term direction.

Server development

The server requires Go 1.25 or newer.

cd server
go run ./cmd/box-manifest-server

SQLite data is stored at server/data/box-manifest.db by default and is ignored by Git.

Run the web development server in a separate terminal. It proxies API requests to the Go server and serves the client at http://localhost:5173:

cd web
npm install
npm run dev

For a production-style local build, run npm run build before starting the Go server. The server serves the generated web/dist directory at http://localhost:8080.

Container deployment

The root Dockerfile builds the web client and Go server into one image. Run it locally with a persistent data volume:

docker build -t box-manifest .
docker run --rm -p 8080:8080 -v box-manifest-data:/data box-manifest

Kubernetes resources in k8s/ deploy one server replica with a persistent SQLite volume at /data. The deployment intentionally uses the Recreate strategy so two server processes never write the database during an update.

Pushes to master build and publish an immutable image to the Gitea registry, then deploy it to the nicholas namespace. The repository requires these Gitea Actions secrets:

CD_CD_BUILD_PUSH: registry token with package write access
KUBE_CONFIG: base64-encoded kubeconfig for the namespace deployer account

Available options:

go run ./cmd/box-manifest-server \
  -address :9000 \
  -database /path/to/box-manifest.db \
  -web ../web/dist

Run server tests with:

cd server
go test ./...

The API contract is api/openapi.yaml. The nested AI-import format is api/tree-import.schema.json.

CLI

Build the CLI from the server module:

cd server
go build -o box-manifest ./cmd/box-manifest

It defaults to http://box-manifest.hosts.uuard.com:8080. Override that with --server before the command or with BOX_MANIFEST_SERVER_URL:

./box-manifest server show
./box-manifest tree
./box-manifest search "soldering iron"
./box-manifest node create --parent unsorted --name "Soldering iron"
./box-manifest export --output inventory.json

Successful output is JSON. Errors are JSON on standard error with a nonzero exit status. Run ./box-manifest help for command groups. The api METHOD PATH --data JSON escape hatch provides access to every endpoint. The complete command reference is docs/CLI.md.

Android development

The debug client defaults to http://box-manifest.hosts.uuard.com:8080. Its server can be tested and changed from Application settings in the app.

Build and verify from the command line with:

JAVA_HOME=/opt/android-studio/jbr \
ANDROID_HOME="$HOME/Android/Sdk" \
./gradlew :android:assembleDebug :android:testDebugUnitTest :android:lintDebug

The QR scanner uses Google Play services and may download its scanner module the first time it is opened. Label URLs use the server selected in Application settings.