Get started

ShelfKeeper runs on your Android phone on its own. Install it, open it, and scan something. Sharing it between phones, or running your own server, is optional and can come later.

1. Get the app

1. Install ShelfKeeper from Google Play:

   

   Or download the APK directly.

2. Open it. There is no account and nothing to set up: it works on the phone by itself. (Settings calls this Phone only.)
3. Scan a barcode. The app downloads its own offline product database, so many products fill themselves in even without a signal.
4. Point the camera at the best-before date, check it, and save.

2. Optional: share it between phones

Every phone in the household can share one list, over your home Wi-Fi. Sharing between phones is part of ShelfKeeper Plus; one purchase covers every paired phone.

1. On one phone, open Settings, find Household hub and tap Make this phone the hub, then Show pairing code.
2. On each other phone, open Settings and tap Scan a pairing code.

The hub phone keeps the household's list; the others sync with it when they are on the same network.

3. Optional: your own server

You don't need a server to use ShelfKeeper. Run one if you want an always-on copy of the household's stock, a web interface for it in any browser, or an AI assistant. It is free, and a Raspberry Pi is plenty.

Debian, Ubuntu 24.04+, or Raspberry Pi OS (32- or 64-bit)

1. Add the package repository and install:

   sudo install -d -m 0755 /etc/apt/keyrings
   sudo curl -fsSLo /etc/apt/keyrings/shelfkeeper.gpg https://www.shelfkeeper.co.uk/apt/shelfkeeper.gpg
   sudo curl -fsSLo /etc/apt/sources.list.d/shelfkeeper.sources https://www.shelfkeeper.co.uk/apt/shelfkeeper.sources
   sudo apt-get update && sudo apt-get install -y shelfkeeper

2. The server runs as a service straight away, on port 8080. Read the generated household key with:

   sudo grep api_key /etc/shelfkeeper/config

3. Open http://<server-ip>:8080/ in a browser and sign in with that key.
4. Updates arrive with your normal sudo apt upgrade. Check on it with sudo systemctl status shelfkeeper or journalctl -u shelfkeeper. The port and other settings live in /etc/shelfkeeper/config – restart the service after editing.
5. The offline product database needs no build step: in the web UI, open Settings, find the Product database card and press Update product database. It downloads and verifies the signed dump from www.shelfkeeper.co.uk.
6. Pair each phone: in the app's Settings, set the mode to Server, then either type the server's URL and the household key by hand, or scan the QR code on the web Settings page's "Pair a phone" card. Over HTTPS that QR carries a one-time pairing code; over plain HTTP it instead shows a plainer QR carrying the key itself behind a warning – keep that QR as private as the key.

Other Linux

1. Download the binary that matches your machine and install-service.sh from the downloads page.
2. Run it against the binary you downloaded:

   bash install-service.sh ./shelfkeeperd-linux-<arch>

   It installs a systemd user service and, on first run, generates a household key in ~/.local/share/shelfkeeper/config. Read it back with:

   grep api_key ~/.local/share/shelfkeeper/config

3. The script prints a couple of lines about building offimport when you gave it a prebuilt binary – ignore them; you don't need it (next step).
4. Open http://<server-ip>:8080/ in a browser and sign in with that key.
5. The offline product database needs no build step: same as above, use the Update product database button in Settings.
6. Pair each phone: same as above.

Problems

Report a problem (or, in the app, Settings → Report a problem), or email [email protected].

Need help? Ask on Discord, where other ShelfKeeper users and the team answer questions. For anything private, email [email protected] instead.