A self-hosted shared shopping list for one household. A phone each, an installable PWA, and a single SQLite file behind a FastAPI server — no cloud account, no subscription, no third-party anything.
It's fast where it counts: an optimistic, offline-first list you can read and tick off in a shop with no signal, passkey sign-in so there are no passwords to type at the door of a store, a voice-ring capture endpoint that drops "milk, eggs and bread" straight onto the list, and an MCP server so Claude can read and edit the list for you. No LLM key needed — groceries arrive iconed and sorted into aisles out of the box.
Ask Claude to stock the list — it fills in live, iconed and sorted into aisles.
curl -fsSL https://raw.githubusercontent.com/maxdraki/trug/main/install.sh | shNeeds Docker, Compose v2 and curl already installed — it checks for all three and names the fix
if one is missing, but it won't put a container runtime on your machine behind your back. It
handles the rest: ~/.trug, all four tokens, the image, the container, and a trug command —
up, down, status, logs, share, set-origin, doctor. Those work from any directory,
which the raw docker compose lines below do not. Re-running the installer is the repair path; it
never touches your data or a live token.
On a first install it prints your bootstrap token at the end. Open http://localhost:8000, choose
"use an access token", paste it, create your passkey. Then trug share for a link and a QR the
rest of the house can open.
→ details, and the Raspberry Pi notes
Railway builds Trug, attaches the volume, generates your tokens and works out the passkey settings
from your new domain. Open the URL it gives you, paste TRUG_BOOTSTRAP_TOKEN from the Variables
tab, pick a name, create a passkey. Runs on the Hobby plan, about $5/month.
→ details
A Mac, a NAS, a Raspberry Pi. One container, one SQLite file.
git clone https://github.com/maxdraki/trug.git
cd trug
docker compose pull && docker compose up -d
docker compose logs | grep TRUG_BOOTSTRAP_TOKENOpen http://localhost:8000, choose "use an access token", paste that token, and create your
passkey. Then invite the household from Settings → Members.
The cd is load-bearing. Compose commands need a docker-compose.yml in the directory you're
standing in, so run these in the clone or you'll get no configuration file provided: not found.
Pull before you bring it up — there's a build: . in the compose file, so a plain up compiles
from source instead of taking the 30-second image.
→ full walkthrough, including a Raspberry Pi
Passkeys need HTTPS or literal localhost. A phone at http://192.168.1.5:8000 will load the
list and then refuse to create an account, because browsers won't make a passkey in an insecure
context. trug share is the no-setup way round it for the same wifi; a real HTTPS name plus
trug set-origin is how you do it properly.
Everything lives on one screen, grouped into store-order aisles. Settings tuck away into collapsible sections — theme (Mocha, Latte, and the rest of Catppuccin), accent colour, your signed-in devices, invite links, and the connection details for AI assistants and the ring.
Your whole instance is one SQLite file, so a backup is one command and a restore is three.
Trug does one thing — make Saturday's shop faster for one household — and deliberately refuses everything else. The non-goals, which are the deliberate event horizon:
- No recipes, meal planning, or pantry inventory. Those are a different product.
- No passwords and no admin tiers. A flat, invite-based passkey roster — no registration forms, no password resets, no owner/admin hierarchy.
- No multi-tenancy. One household per instance; nothing household-specific is baked into the code.
- No native apps or Play Store. Installable PWA only.
- No price tracking, budgets, or store loyalty anything.
Any feature request gets tested against: "does this make Saturday's shop faster?" If no → parking lot.
| Install | The one-liner, Railway, Docker Compose, a Raspberry Pi, your own fork |
| Remote access | Getting phones on it — trug share, Tailscale, your own domain, tunnels |
| Configuration | Every setting, and config.yaml |
| Running it | Backups, restores, upgrades, the doctor, recovery |
| Integrations | MCP for Claude, the Pebble ring, bring-your-own LLM key |
| Hosting | For platform operators — the image, the volume, the UID, the one fiddly setting |
| Troubleshooting | Symptoms and fixes |
Deploying it with Claude Code. This repo ships a skill that walks the whole self-host through
for you. Clone it, open Claude Code, and say "deploy trug" — the
deploy-trug skill collects your domain, brings the stack
up with Compose or Railway, verifies the first boot, and mints the passkey invites.
See CONTRIBUTING.md for the development setup — pytest in server/,
vitest in web/, and docker compose up for the lot.
MIT — see LICENSE. Copyright (c) 2026 Trug contributors.
Trug is themed with Catppuccin, and bundles Tabler Icons and the Inter and Space Grotesk typefaces. Full license texts for the redistributed assets are in THIRD-PARTY-NOTICES.md.



