Install in one command

Get started

Pick the install that matches where you want it to run. Every path ends at the same web setup wizard, so there are no config files to edit.

Where it lands

One web setup wizard

However you install, you finish at /setup: set a password, add an AI key if you want one, run live connection tests, and save. A bundled Grocy connects itself. No config files to edit, and every section saves on its own.

Raspberry Pi kitchen appliance

Turn a Raspberry Pi into a dedicated Pantry Raider appliance, optionally with a touchscreen kiosk and a Stream Deck.

Minimum hardware

PartMinimumRecommended
BoardRaspberry Pi 4B, 2 GBRaspberry Pi 5, 4 GB or more
Storage16 GB microSD32 GB or more, A2-rated (or boot from SSD)
OSRaspberry Pi OS Lite, 64-bit
PowerOfficial USB-C supply
Kiosk (optional)Not neededDSI or HDMI touchscreen, plus a Stream Deck

The full stack (Pantry Raider plus Grocy) runs comfortably on a 2 GB Pi; add Mealie and you want 4 GB or more. Fully local Ollama AI is a mini-PC job (16 GB+), so on a Pi, use a cloud AI provider instead. An older 1 GB Pi 3B+ still earns its keep as a thin kiosk remote for a server elsewhere; a Pi Zero 2 W is too small even for that. The tested boards are the Raspberry Pi 5 and 4B (4 GB and 8 GB); a 2 GB Pi 4B works with limits.

Install

Flash stock Raspberry Pi OS Lite with Raspberry Pi Imager (set wifi, hostname, and SSH there), boot, SSH in, and run:

curl -fsSL https://raw.githubusercontent.com/Syracuse3DPrintingOrg/PantryRaider/main/install.sh | bash

The installer detects the board, any attached display, and any Stream Deck, then asks which deployment mode and add-ons you want. It can also run as a thin kiosk remote (a Bandit) that drives a display and Stream Deck for a Pantry Raider server hosted elsewhere.

When it finishes, open http://pr.local:9284/setup (or the address the installer prints) and follow the wizard.

There is also a pre-built appliance image on the Releases page that skips the SSH step. It is in beta and best for people comfortable editing setup files: before the first boot you add your Wi-Fi, login account, and timezone to text files on the card, and it always installs the full stack (no thin remote, no add-on choices). It is tested on the Raspberry Pi 4B and Pi 5. The SD-card guide covers both paths.

Wiring up a sensor, a wired barcode scanner, a PoE HAT, or a STEMMA QT / Qwiic board? See which header pins each accessory uses, and where pin 1 is on the board.

๐Ÿ”Œ Open the interactive GPIO guide

Mini PC kitchen server

An x86-64 mini PC (Intel N100 class or better) makes a quiet, always-on Pantry Raider box that runs the whole stack, and it is the best choice for fully local AI with Ollama. Run it headless for the rest of the house, or attach a touchscreen and it becomes its own kitchen kiosk.

Minimum hardware

PartMinimumRecommended
CPU64-bit x86 (Intel N100 class)N100 or better
RAM4 GB8 GB, or 16 GB or more for local Ollama AI
Storage16 GB32 GB or more, SSD or NVMe
OS64-bit Linux with Docker and Compose v2Debian or Ubuntu Server
NetworkEthernet or Wi-FiEthernet for an always-on box

Install

Install Docker with Compose v2, then one command pulls the prebuilt image and starts Pantry Raider plus a bundled Grocy inventory backend:

curl -fsSL https://raw.githubusercontent.com/Syracuse3DPrintingOrg/PantryRaider/main/scripts/install.sh | bash

Then open http://YOUR-HOST:9284/setup and follow the wizard. For a fully local, private setup, add the with-ollama profile and pick Ollama as your AI provider, with no cloud key needed.

Docker on a server or NAS you already run

Already have a NAS, Proxmox, TrueNAS, or Unraid box? Add Pantry Raider alongside your other services. It needs Docker 24 or newer with Compose v2. One command pulls the prebuilt image and starts Pantry Raider plus a bundled Grocy inventory backend:

curl -fsSL https://raw.githubusercontent.com/Syracuse3DPrintingOrg/PantryRaider/main/scripts/install.sh | bash

Then open http://YOUR-HOST:9284/setup and follow the wizard: set a password (required by default), add an AI provider key if you want photo and receipt scanning, test, and save. You do not need a Grocy key: on first run Pantry Raider signs in to the bundled Grocy, creates its own key, and secures the Grocy admin account.

Prefer to do it by hand? In an empty folder, download the compose file and the small Grocy start-up script it uses, then start the stack with the with-grocy profile:

curl -fsSL https://raw.githubusercontent.com/Syracuse3DPrintingOrg/PantryRaider/main/docker-compose.prod.yml -o docker-compose.yml
mkdir -p docker/grocy-init
curl -fsSL https://raw.githubusercontent.com/Syracuse3DPrintingOrg/PantryRaider/main/docker/grocy-init/10-repair-auth-class.sh -o docker/grocy-init/10-repair-auth-class.sh
chmod 755 docker/grocy-init/10-repair-auth-class.sh
docker compose --profile with-grocy up -d

The start-up script must be executable, or Grocy skips it. Leave out --profile with-grocy only if you already run Grocy elsewhere. These steps follow the install section of the README, which is always the current version.

On Unraid, skip the script: install the Pantry Raider template from Community Applications, or bring up the whole stack with the Docker Compose Manager plugin. The Unraid guide covers both.

Optional extras start with Compose profiles. Add any you want to the up command:

ProfileAdds
with-grocyGrocy, the inventory backend (started by default in the install script)
with-mealieMealie, for people who already use it (recipes, meal plans, and shopping lists also work without it)
with-ollamaOllama for fully local AI, no cloud key needed
with-printingA CUPS print stack for label and document printing to network printers
with-beszelBeszel host and container monitoring

Home Assistant add-on

Runs inside Home Assistant OS or Supervised, with the UI in the sidebar and no separate login (Home Assistant handles auth through Ingress). In Settings > Add-ons > Add-on Store, add the repository https://github.com/Syracuse3DPrintingOrg/PantryRaider, install Pantry Raider, and start it. Install the communityGrocy add-on first: unlike the Docker paths, the add-on does not bundle the inventory backend, and the setup wizard points Pantry Raider at it.

Already running Pantry Raider on another box? You want the separateHome Assistant integration instead: install it through HACS and pair with a code on the kitchen screen for live sensors, notifications, and camera pop-ups with no key pasting.

Deployment modes

The setup wizard picks between three modes, so the same software fits very different homes:

ModeWhat it is
ServerPantry Raider on a NAS, mini PC, or VM, connected to Grocy (and optionally Mealie) running alongside it
Pi applianceEverything on one Raspberry Pi, with the kiosk auto-enabling when a display is attached
Kiosk satelliteA thin Pi that drives a touchscreen or Stream Deck for a server elsewhere on your network, pulling its config automatically. Even a 1 GB Pi 3B+ works in this role

Updates arrive on their own: a Docker server through its bundled updater, a Pi appliance or a server set up with the install script from signed releases it checks before installing, and satellites follow their server's version.

Reach it from outside your kitchen

Out of the box the app serves plain HTTP on your home network. For HTTPS or remote access, put your own reverse proxy (Caddy, nginx, Traefik, or Pangolin) in front of it to handle TLS, or use Forager remote access, which publishes the app over HTTPS without opening a port. The platforms guide and the remote access guide cover both.

Anything that arrives through a reverse proxy or a tunnel counts as coming from the internet, even when the proxy runs on the same machine. A kitchen reached that way needs a password, and signing in from outside your home network also needs two-factor. Turn on two-factor in Settings, Security from a device at home. A kitchen with no password does not answer through a proxy at all. The security guide has the full rules.

The setup code

If you open the setup wizard from outside your home network, or you are locked out from outside before two-factor is on, the kitchen first asks for its setup code. It is in the app's log, on the newest line that begins Pantry Raider setup code. With Docker Compose or on a Raspberry Pi, run:

sudo docker logs foodassistant-service 2>&1 | grep "setup code"

On Unraid, open the Docker tab, click PantryRaider, and choose Logs. In the Home Assistant add-on, open the add-on's Log tab. A code works once, within 24 hours. Setting up from a device on your home network does not need it.

AI is optional

Everything except the AI extras (photo and receipt scanning, product name cleanup, AI recipe writing, and shelf-life estimates) works with no AI provider at all. When you want it, bring a Gemini, OpenAI, or Anthropic API key, or run local models with Ollama for a fully private, offline-capable setup. Gemini has a generous free tier and is the default cloud choice.

Common questions

What does it cost?

Nothing for personal use. Pantry Raider is source available under the PolyForm Noncommercial 1.0.0 license: free for personal, educational, and other noncommercial use. Self-hosting has no subscription. Forager, the optional hosted companion, adds remote access and pooled AI from $10/year, and you never need it.

Does my data leave my network?

Your food data does not. Inventory lives in your own Grocy database on your hardware. The outbound calls are the ones you use or configure: a cloud AI provider (skippable with Ollama), an Open Food Facts lookup when you scan a barcode (type item names in by hand and none is made), weather forecasts from Open-Meteo (the panel can be turned off), recipe search from TheMealDB (can be turned off; your own library stays local), and rclone cloud backups if you set them up. Two small things are on from the start: the update check (GitHub) and a once-a-day download of the community shelf-life table from Forager, which carries nothing about you. Both can be turned off, and there is no telemetry. The what needs the internet page lists every one.

Do I need Grocy or Mealie accounts?

No accounts, they are self-hosted too. Grocy is the inventory backend and the install script starts it for you. Recipes and meal planning are built into Pantry Raider itself, and the shopping list lives in Grocy, so Mealie is fully optional; connect it only if you already use it.

Can it run fully offline?

Mostly, after the initial install. First-time setup needs internet to pull the images. From then on, with Ollama as the AI provider, day-to-day use, startup, and restarts work with no internet access. Turning a scanned barcode into a product name needs Open Food Facts, so offline you type the item name instead.

Is it stable?

Not yet. Pantry Raider is beta software, pre-1.0 and under active development. It runs in real kitchens today, but features and settings can still change between updates. Backups are built in: take one before you update, and report problems on GitHub issues.

More detail

The GitHub repository has the full README, compose files, and hardware guides, and the documentation index links out to the documentation site for the longer guides.

Up and running in one command

A dedicated Raspberry Pi kitchen appliance, Docker Compose on any server or NAS, or a Home Assistant add-on.

Try the live demo