# Gemmein

> Gemmein is the backend for web and mobile apps: hosting, sign-in, protected data, payments, AI tools and a dashboard to run your customers.

Build with any AI coding tool; building is local and free. This is a
short index. The full guide, with every rule, error code and method, is
https://docs.gemmein.com/llms-full.txt.

## Docs

Paths are on https://docs.gemmein.com. Each path below is a page's markdown twin; without .md it is the HTML page, which also answers Accept: text/markdown with the same markdown. Each line says what the page answers.

- /llms-full.txt — everything in one file
- /changes.txt — what changed, every release
- /llms-dashboard.txt — dashboard steps
- /errors/<code>.md — one page per error code

Get started:
- /index.md — start here
- /quickstart.md — install, run locally, move to the cloud
- /mcp.md — MCP tools, hosted connector, check_integration

Sign-in & sessions:
- /auth.md — how sign-in works
- /auth/sign-in.md — codes, sessions, sign-out, resend limits
- /auth/devices.md — signed-in devices, IP addresses
- /auth/what-happens-if.md — sign-in cases
- /auth/account-deletion.md — delete a person's account
- /auth/data-export.md — export a person's data

Data:
- /data.md — where data lives, who reads it
- /data/collections.md — collections, records, filters, totals
- /data/safety-rules.md — the eight safety rules
- /data/messages.md — messages, group chats, links
- /data/files.md — uploads, sealed and public files
- /data/publishing.md — approval queues, likes, votes, RSVPs
- /data/live-collections.md — plan-locked collections, live fields
- /data/what-happens-if.md — record and collection cases

Payments:
- /payments.md — how payments work, what's not supported
- /payments/connect-stripe.md — Stripe key, permissions, payments.json
- /payments/subscriptions.md — plans, free trials, changing plan
- /payments/one-off-purchases.md — products, guest checkout, purchase email
- /payments/access.md — what a purchase unlocks, manual grants
- /payments/refunds.md — refunds, receipts, deleted accounts
- /payments/what-happens-if.md — comps, Stripe and subscription cases
- /payments/what-happens-if-purchases.md — trial, plan-change, product cases

Credits and conflicts:
- /credits.md — credit packs, spending, grants
- /contention.md — unique names, stock, counters

AI tools:
- /ai.md — AI features priced in credits
- /ai/tools.md — call a tool, providers, aliases
- /ai/provider-keys.md — keys, OpenAI-compatible, pricing
- /ai/runs.md — image, video, speech, transcripts
- /ai/pipeline.md — your own pipeline, local AI
- /ai/what-happens-if.md — AI refunds, limits, cases
- /ai/reference.md — tool fields, numbers, codes

Email:
- /email.md — app email, the Inbox
- /email/sending.md — sending domain, senders, caps
- /email/templates.md — design the app's emails
- /email/what-happens-if.md — sending and Inbox cases

Relays:
- /relays.md — webhooks, schedules, automations
- /relays/relay-files.md — relay files, sync
- /relays/receivers.md — receive webhooks, map fields
- /relays/signatures.md — verify any sender's signature
- /relays/triggers.md — schedules, credits low, record changes
- /relays/actions.md — grant, email, call a URL, write
- /relays/selling.md — sell via Paddle, GoCardless, stores
- /relays/calling-your-url.md — the signed call your server gets
- /relays/failures.md — retries, ordering, cases

Mobile:
- /mobile.md — phone apps
- /mobile/expo-and-swift.md — Expo, Swift, sessions, local dev
- /mobile/store-purchases.md — App Store/Play via RevenueCat
- /mobile/sign-in-and-codes.md — phone sign-in limits, codes

Sites:
- /sites.md — host the frontend, preview, go live

Run:
- /console.md — how the dashboard is laid out
- /console/go-live.md — go live, promote
- /console/domains.md — add and verify domains
- /console/logs.md — who did what

Reference:
- /reference.md — every SDK method, keys, limits
- /errors.md — every error code and fix
- /changelog.md — what changed per release
- /reaffirm.md — test safety rules in CI

Dashboard › Overview, Inbox and Customers:
- /console/overview.md — first page
- /console/inbox.md — answer replies
- /console/customers.md — a person: access, devices, delete

Dashboard › Revenue:
- /console/subscriptions.md — who pays, comps

Dashboard › Build:
- /console/get-started.md — steps to go live, approve your AI
- /console/data.md — collection settings
- /console/records.md — browse and edit records
- /console/payments.md — Stripe, plans, products
- /console/relays.md — relays, senders' secrets
- /console/ai.md — keys, tools, runs

Dashboard › Logs:
- /console/errors.md — refused writes

Dashboard › Settings:
- /console/api-keys.md — secret keys
- /console/usage-and-billing.md — costs, tiers, limits
- /console/notifications.md — alerts you get

## Common tasks → page

- add sign-in → /auth/sign-in.md
- each person sees only their own data → /data/safety-rules.md
- upload files → /data/files.md
- chat between people → /data/messages.md
- connect Stripe → /payments/connect-stripe.md
- subscription with a free trial → /payments/subscriptions.md
- sell a product or download → /payments/one-off-purchases.md
- refund a payment → /payments/refunds.md
- sell and spend credits → /credits.md
- AI feature priced in credits → /ai/tools.md
- OpenRouter, Mistral, Groq… models → /ai/provider-keys.md
- email from my domain → /email/sending.md
- receive a signed webhook → /relays/signatures.md
- run something daily or weekly → /relays/triggers.md
- App Store / Play purchases → /mobile/store-purchases.md
- put my site online → /sites.md
- stop double bookings → /contention.md
- fix an error code → /errors/<code>.md
- go live → /console/go-live.md
## If you are an AI helping someone build

- Talk to the person in plain words: say what happens, in their terms.
- Read one page, not the site: https://docs.gemmein.com/payments/refunds.md is a page's markdown, and https://docs.gemmein.com/search?q=refund+a+payment returns the five best sections with their .md links (&format=json for JSON).
- If the dashboard shows something different from what you read, trust
  the dashboard and re-read the guide.
- If the project folder is empty, ask what they're building, and for whom,
  before assessing anything. If there's already an app, assess whether
  Gemmein fits it and explain any gaps first.
- Ask question 1 before you read the full guide. This index is enough for
  the questions and the verdict; read the full guide
  (https://docs.gemmein.com/llms-full.txt) once building starts.
- Ask one question at a time, in this order, offering choices where they
  exist (use your tool's question picker if it has one): (1) what they're
  building, and for whom; (2) web, mobile, or both; (3) for web: host it
  on Gemmein, or on your own host — and is there a domain you want it on?
  (4) who sees whose data; (5) what people pay for:
  subscription, one-off, credits, or not yet; (6) any AI features: chat,
  image, speech, transcription, video, or their own pipeline.
- Say this early, with question 3: a web app Gemmein hosts goes live at
  <slug>.gemmein.dev; an own domain is optional (up to 5 per Live app).
  A web app hosted elsewhere goes live on a domain the person controls
  (checked with a DNS record). Add any domain on the Domains page from the
  start, even in Development; a host's preview address (like
  name.vercel.app) can't be added. A mobile-only app needs no domain.
- Don't list what Gemmein refuses before the person answers. Raise a
  refusal only when an answer hits one: name it, and the workaround if
  there is one.
- Give the verdict (FITS, FITS EXCEPT, or DOESN'T FIT) before building.
- If it fits, reach five milestones as you build, and name each to the
  person as you reach it: (1) It fits: the verdict above. (2) People can
  sign in: sign-in codes work, from the emailed code to a signed-in
  session. (3) Their data is safe: every collection has a
  server-enforced safety rule; check it with the reaffirm/MCP check
  (https://docs.gemmein.com/mcp) against the development environment.
  (4) They can pay: Stripe built in, a relay, or App Store/Play via
  RevenueCat, connected and tested — a member-writable status isn't proof
  of payment; trust receipts or an entitlement instead. (5) Live, with the
  first person using it.
- Keys: the app key (`pk_…`) is safe to commit. It is public and locked
  to the person's domains, so it belongs in the repo, e.g. in
  `.env.production`. A secret key (`sk_…`) never goes in the repo or the
  app, only in a server's environment.
- Before milestone 5, test the whole flow yourself: sign in as a test
  person with a throwaway test session (sk_dev, no sign-in code; the same
  kind the reaffirm/MCP check uses), pay, run the paid AI feature as that person,
  and spend credits until they run out. `checkout()` and `buy()` return a
  Payment Link. Opening it and paying is the one step the person must do:
  ask them to open the link and pay with a Stripe test card. Then show
  them where to see every step: the Customers, AI and Logs pages in the
  dashboard. The full guide's Rehearsal section has the detail.

## What Gemmein does

- Sign-in: sign-in codes sent by email are the only way in (no
  passwords, no social or OAuth sign-in).
- Data: records live in collections, each under one of eight safety
  rules enforced on the server (`private`, `shared`, `admin_write`,
  `public_read`, `community`, `addressed`, `direct`, `app_only`). No client-side
  filtering. `direct` is messaging between people: a message names one
  person, or up to 20 for a group chat (`{ for: [ids] }`), as one record
  every named person reads.
- Payments: subscriptions and one-off digital products. Stripe is built
  in: the owner connects a Stripe restricted key with 5 permissions, plus
  2 if the app sells plans (Gemmein refuses a key that can do more) and Gemmein
  makes each Payment Link; any provider that signs its webhooks connects through a relay; App
  Store and Play purchases arrive via RevenueCat. Consumable credits: buy
  a pack, spend atomically, never below zero. The dashboard's products and
  plans ARE the catalog: a storefront lists `g.payments.products()` and a
  pricing page `g.subscriptions.plans()` (no sign-in needed); never make a
  collection to list what you sell. In Development you set them: declare
  prices, files, credits and tax categories in gemmein/payments.json and
  `npx gemmein sync` sells them; `npx gemmein payments --cloud` reads
  them back.
- AI tools: a named operation the owner prices in credits and opens only
  to the plans they pick. Kinds: chat, image, speech, transcription,
  video, or your own pipeline as a provider (`provider: "external"`).
  Providers: OpenAI, Anthropic, Google, Deepgram, Replicate, fal,
  AssemblyAI, ElevenLabs or Runway, on the owner's own provider key.
- Runs: a job tool (generate or transcribe) returns a run instead of an
  answer. The provider does the job, Gemmein follows it until it ends,
  and the outputs are saved as sealed files on the person.
- Relays: Gemmein runs them. It receives an event (a webhook, a schedule
  or a record change), maps the fields and carries out its own actions
  (write a record, grant access, email the person, call your URL, or run
  one Edge function you pushed, with a declared reach).
- Dashboard (app.gemmein.com): where the owner manages people,
  subscriptions, payments, relays, AI, going live, logs, problems and
  alerts. Guides: https://docs.gemmein.com/console
- Security is on by default for every app: tenant isolation, rate
  limiting, audit logs and domain-locked keys, with nothing to configure.

## What Gemmein refuses (raise one only when an answer hits it)

- Android or iOS written natively in Kotlin or Java (the mobile SDKs are
  `@gemmein/sdk/expo` for Expo/React Native and `GemmeinSwift` for Apple)
- password or social/OAuth sign-in
- team, group or workspace visibility, or per-person record permissions
  (each app has one owner and the people who use it)
- carts, quantities, physical goods, shipping, inventory
- usage-based invoicing (a bill after the fact, by token or by minute);
  prepaid consumable credits are supported (see above)
- seats (not planned)
- a long-running server or an arbitrary cron outside a relay: Edge
  functions cover one bundled module of your own code, with a declared
  reach, run by a relay's run_function on a webhook, schedule or record
  change, pooled and paused (not charged) past the plan's allowance;
  anything bigger runs on your own host instead
- custody of money (the owner's own payment provider holds funds;
  Gemmein never does)
- multi-seller payouts or revenue splits (every payment lands whole in
  the owner's own payment provider account: Stripe built in, others
  through a relay; Gemmein never holds it)

### The three verdicts

- FITS: every requirement maps.
- FITS EXCEPT: name each gap and its workaround, or say there is none;
  the person decides. If a gap breaks the app's main feature, the
  verdict is DOESN'T FIT.
- DOESN'T FIT: say so, say why, and stop.

## How to start

There are two starting points: an idea with nothing built yet, or an app
that already exists and needs a backend. Ask the questions and give the
verdict first. Once building starts, read the full guide
(https://docs.gemmein.com/llms-full.txt): it has the in-scope map, worked
refusals and the build order. Then:

1. `npx -y gemmein dev` starts a local backend with no signup, no account
   and no keys. Building is local and free.
2. Ask the person the business questions, and build from their answers.
3. Build in the order the product enforces: sign-in, then the safety
   rules (one per collection), then what people pay for.
4. When it works locally, the person signs up free at app.gemmein.com
   and approves `npx gemmein login` in the browser (no key is pasted).
   `npx gemmein sync` is the first cloud step: it links the project and copies
   your collections, AI tools and relays into development. Going live
   comes after (`npx gemmein go-live`). It needs at least one collection;
   a verified domain, unless the app is mobile-only; an active Gemmein
   subscription (the go-live payment; from $29 a month for the account); for
   a mobile-only app, the owner's confirmation that no secret key ships in
   it (the dashboard's tick or `--confirm-no-secret-key`) or a CLI scan
   that read the built app; and accepting Gemmein's terms. Payments and
   the AI provider key can be set up after going live. From then on,
   `npx gemmein sync --live`, approved in the browser each time, copies
   relays and AI tools to live.

## Pricing

- Free to build. You pay when an app goes live — or buy ahead if you're ready. Development is free, up to 3 apps.
- One plan per account: putting an app live puts the whole account on a tier its founder picks — Launch $29, Run a business
  $79 or Grow $199 a month, or annual at 2 months off ($290, $790, $1,990 a
  year) — up to that tier's own number of apps (5, 10 or 25). Launch and Run a business include 100,000 active people a month; Grow has no visible limit.
- Above 25 apps, the price is agreed with Gemmein. Every limit, per
  tier: https://docs.gemmein.com/console/usage-and-billing#limits