merran-app/merran

Your recipes. Your kitchen. Your server.
A self-hosted meal planner for households, with an optional AI cooking assistant.

Documentation · Install · API · Releases · Report a bug

Still images: Today · Recipes · Plan

Light-mode app previews with sample data and AI-generated recipe photos. The slideshow changes view every 4.5 seconds; use the links above for still images.

One loop, every week

• Collect recipes from websites, write your own, or migrate from Mealie and other supported apps.
• Plan meals with serving counts, theme preferences, and suggestions from your library.
• Shop and track the pantry with shared lists, combined quantities, and food you already have accounted for.
• Cook at the counter with step-by-step instructions, ingredient checklists, and timers.
• Add AI when you want it for imports, substitutions, and an assistant that proposes kitchen changes for review.
• Make it yours with separate households, three palettes, a browser extension, and an API with scoped keys.

Core recipes, planning, lists, and pantry tracking work without AI. AI, nutrition, voice, and store connections have their own setup requirements. Start with your first week.

Get started

The installation guide includes TrueNAS, Dockge, and Portainer examples, plus complete Postgres, Kokoro voice, and tunnel setup. The project's compose.yaml also has FlareSolverr, for importing from sites that turn servers away (not released yet).

Merran runs in one Docker container with SQLite included. Postgres is optional. The image includes application dependencies; no separate Node package installation is needed on the host.

Use the :next release channel while Merran is in alpha:

mkdir data
docker run -d --name merran --restart unless-stopped \
  -p 3000:3000 -v "$(pwd)/data:/data" ghcr.io/merran-app/merran:next
docker logs merran

Open http://YOUR-SERVER:3000 and use the setup code from the log to create your account and household.

Merran is in alpha. next follows published releases, including alphas; edge follows development on main. Until the first full release, latest is the same as next; from then on it follows full releases only and becomes the recommended tag. You can pin a specific published version if you prefer to choose when to change versions. Never delete the persistent data directory when recreating Merran: it contains the database, photos and server secret. Back up the complete directory before updating.

See the installation guide for Docker Compose and image tags, and updating and backups for maintaining your server.

Find your way

I want to…	Start here
Import and organize recipes	Recipes
Plan, shop, and cook	Planning · Shopping and pantry · Cooking
Set up AI and understand costs	AI setup · Privacy and data flow
Configure or fix my server	Configuration · Troubleshooting
Connect another tool	API quickstart · OpenAPI schema
Install the browser extension	Extension guide

Visit merran.app for the product overview, documentation, and API reference.

See the public roadmap for what is up next, planned features, and ideas open for feedback.

Contribute

Bug reports, documentation improvements, and code contributions are welcome. See the contributor guide.

For local development, use Node 24 and the repository's pinned pnpm version:

corepack enable
pnpm install
pnpm dev

The app runs on http://localhost:5173, with its API on port 3000. Run pnpm docs:dev for the public site. Development checks and API-generation commands are covered in the contributor guide; internal plans live in docs/.

For repeatable setup development: set MERRAN_DEV_SETUP=on in the shell before pnpm dev to use a fresh temporary SQLite database on every server start. The normal database is untouched; the flag is rejected in production and Docker installs. See setup development. Alpha.4 also provides docker exec merran merran setup-code to retrieve a buried setup code and docker exec -it merran merran reset-password USERNAME for operator recovery.

Read AGENTS.md for repository conventions and what to update with each change. Pull request titles use a kind such as feat:, fix:, or docs:; release drafts are assembled from merged PRs. See the release process before running the Release workflow on main.

License

Copyright © 2026 Kyle Johnson. Merran is licensed under AGPL-3.0-or-later. Public documentation is shared under CC BY 4.0.