Quickstart

Deploy your own copy (Deploy button), sign in, open Settings, then API keys, create a key, and copy the plaintext value (shown once). Call https://<your-app>.vercel.app/api/v1 with Authorization: ApiKey rkapi_... and connect MCP at https://<your-app>.vercel.app/mcp.

Just looking? The public demo at https://ovenlovin-demo.vercel.app issues a 24h sandbox key at /api/demo/enter?format=json.

Deploy to Vercel

The fastest way to get started is to deploy OvenLovin to Vercel with one click using the button above.

The one-click deploy will:

Clone the repository to your GitHub account
Create a new Vercel project
Provision Neon Postgres, Vercel Blob, and Clerk (auto-configures DATABASE_URL, the blob token, and Clerk keys)
Prompt for an optional instance name (USDA is optional; AI Gateway uses OIDC on Vercel)
Run database migrations during the Vercel build
Deploy the Next.js app

If the Clerk store is not offered, set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY in the Vercel project.

Environment Variables

Variable	Description	Get It
`DATABASE_URL`	Neon Postgres connection string	Auto-configured by the Neon store
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Clerk publishable key	Auto-configured by the Clerk store, or clerk.com
`CLERK_SECRET_KEY`	Clerk secret key	Auto-configured by the Clerk store, or clerk.com
`BLOB_READ_WRITE_TOKEN`	Vercel Blob storage token	Auto-configured by the Blob store
`AI_GATEWAY_API_KEY`	Optional; on Vercel, AI Gateway uses OIDC (`VERCEL=1` or `VERCEL_OIDC_TOKEN`)	OIDC docs
`USDA_FDC_API_KEY`	Optional; reserved for FoodData Central nutrition (not read today). Not required to deploy	fdc.nal.usda.gov
`RK_MODEL_DEFAULT`	Optional paste-import model. Default `deepseek/deepseek-v4.1-flash`	Leave unset for DeepSeek
`RK_MODEL_VISION`	Optional photo-import model. Default `deepseek/deepseek-v4.1-flash`	Leave unset for DeepSeek
`RK_MODEL_EXTRACT`	Optional URL-import text model after JSON-LD/HTML miss. Else `RK_MODEL_DEFAULT`, then DeepSeek. DeepSeek failures retry `openai/gpt-6-luna`	Leave unset for DeepSeek
`NEXT_PUBLIC_INSTANCE_NAME`	Optional landing-page name	Defaults to `Your OvenLovin`
`OVENLOVIN_VERCEL_TEAM_SLUG`	Optional Vercel team slug for dashboard links (not the GitHub owner)	From the Vercel dashboard URL
`OVENLOVIN_VERCEL_PROJECT_SLUG`	Optional Vercel project slug if it differs from the git repo name	Vercel project settings
`VERCEL_TOKEN`	Optional; resolve slugs from `VERCEL_PROJECT_ID` when overrides are unset	Account tokens
`NEXT_PUBLIC_APP_URL`	Optional public origin for problem+json types and OpenAPI servers	Your deploy URL
`NEXT_PUBLIC_CLERK_SIGN_IN_URL` / `NEXT_PUBLIC_CLERK_SIGN_UP_URL`	Clerk sign-in and sign-up paths	Defaults `/sign-in` and `/sign-up`
`RECIPE_IMPORT_CACHE_FALLBACK`	Optional. `0` skips Google Translate / Jina public copies	Leave unset to try copies
`NEXT_PUBLIC_IOS_SHORTCUT_URL`	Optional iCloud link for the iOS shortcut	Leave unset for manual steps
`E2E_AUTH_BYPASS`	Signed-in kitchen harness only. Never set on Vercel production	See README
`OVENLOVIN_DEMO_MODE` / `OVENLOVIN_DEMO_PROJECT` / `CRON_SECRET` / `NEXT_PUBLIC_DEMO_URL`	Public demo project only. Never on product production	docs/demo.md

Local Development

Prerequisites

Node.js 20 or later
pnpm 9 or later
PostgreSQL database (or use Neon)

Installation

OvenLovin is a pnpm workspace. Run corepack enable first; npm and yarn are not supported.

# Clone the repository
git clone https://github.com/tbarho/ovenlovin.git
cd ovenlovin
 
# Set up environment variables
cp .env.example apps/web/.env.local
# Edit apps/web/.env.local with your API keys
 
# Install dependencies
pnpm install
 
# Start Postgres (or use your own at the DATABASE_URL below)
docker compose -f docker-compose.e2e.yml up -d
 
# Run database migrations (reads DATABASE_URL from the shell, not .env.local)
export DATABASE_URL=postgresql://ovenlovin:ovenlovin@localhost:5432/ovenlovin
pnpm db:migrate
 
# Start development server
pnpm dev

The app will be available at http://localhost:3000.

Development Commands

OvenLovin is a pnpm workspace. Run corepack enable first; npm and yarn are not supported.

# Run all workspaces in dev mode
pnpm dev
 
# Run specific workspace
pnpm --filter @ovenlovin/web dev
pnpm --filter @ovenlovin/core test:watch
 
# Build
pnpm build
 
# Test
pnpm test
pnpm test:watch
 
# Lint & format
pnpm lint
pnpm format
pnpm typecheck
 
# Clean
pnpm clean

Talk to this instance

Send Authorization: ApiKey rkapi_... or Bearer with the same key or a Clerk JWT. Clerk users must already have an OvenLovin kitchen (open the app in the browser once; MCP does not create one). On MCP with a Clerk JWT, optional X-Kitchen-Id selects a kitchen you belong to. An API key is bound to one kitchen; a mismatched X-Kitchen-Id is rejected.

REST lives at /api/v1. Meal-plan checks are POST.

curl -H "Authorization: ApiKey YOUR_OVENLOVIN_API_KEY" \
  https://<your-app>.vercel.app/api/v1/recipes

curl -X POST \
  -H "Authorization: ApiKey YOUR_OVENLOVIN_API_KEY" \
  https://<your-app>.vercel.app/api/v1/meal-plans/PLAN_ID/check

MCP (Streamable HTTP):

{
  "mcpServers": {
    "ovenlovin": {
      "url": "https://<your-app>.vercel.app/mcp",
      "headers": {
        "Authorization": "ApiKey YOUR_OVENLOVIN_API_KEY"
      }
    }
  }
}

Next Steps

Connect Your Agent - Set up Grok Bot, ChatGPT, or Claude Desktop
Learn Concepts - Understand households, rules, and meal planning
API Reference - Explore the REST API and MCP tools

Quickstart

On this page