Environment variables#
Copy .env.example to .env for local runs. Everything here is optional except where noted; the app boots without it and degrades to a local-only configuration.
Never commit a real .env. On Vercel, set variables in Project Settings → Environment Variables and redeploy; build-time values are read by scripts/seo.mjs.
Server#
| Variable | Default | Purpose |
|---|---|---|
PORT |
4178 |
HTTP port for the Node server |
Local npm run dev runs two processes: Vite on 5173 and the API on 4178, with /api proxied. npm start after npm run build serves everything from PORT.
Database#
Local development uses SQLite through node:sqlite. Vercel has no persistent disk, so production must use Postgres.
| Variable | Default | Purpose |
|---|---|---|
REMINDIFY_DATA_DIR |
./data |
Directory for the SQLite file |
REMINDIFY_DB |
./data/remindify.db |
Full path to the SQLite database |
DATABASE_URL |
— | Postgres connection string; when set, SQLite is ignored |
POSTGRES_URL |
— | Accepted alias for DATABASE_URL |
POSTGRES_PRISMA_URL |
— | Accepted alias, useful on Vercel/Neon |
POSTGRES_URL_NON_POOLING |
— | Accepted alias for direct connections |
DATABASE_SSL |
true when a URL is set |
Set false only for local Postgres without TLS |
PG_POOL_MAX |
2 |
Connection pool ceiling per instance |
PG_NO_LOCK |
— | 1 disables the workspace advisory lock; tests only |
Use exactly one Postgres URL. The server picks the first one it finds in that order, and every instance that shares a database must share the same secret and origin configuration.
Origin and cookies#
| Variable | Default | Purpose |
|---|---|---|
PUBLIC_ORIGIN |
http://localhost:4178 |
Canonical origin for OAuth redirects, PayPal return URLs, canonicals and sitemap |
COOKIE_SECURE |
inferred from x-forwarded-proto |
Force Secure cookies on or off |
Set PUBLIC_ORIGIN to the real HTTPS URL before going live. A wrong origin breaks Google OAuth redirect matching, sends PayPal returns to the wrong host and writes the wrong canonical URLs into the build.
Search and AI discovery#
| Variable | Default | Purpose |
|---|---|---|
GOOGLE_SITE_VERIFICATION |
— | Emits the Google verification meta tag at build time |
BING_SITE_VERIFICATION |
— | Emits the Bing verification meta tag at build time |
These are read by scripts/seo.mjs, not at runtime, so they only apply to prerendered HTML. PUBLIC_ORIGIN feeds the sitemap, canonicals and JSON-LD.
Google OAuth#
Optional. Without it, email and password sign-in still works.
| Variable | Default | Purpose |
|---|---|---|
GOOGLE_CLIENT_ID |
— | OAuth client ID |
GOOGLE_CLIENT_SECRET |
— | OAuth client secret |
GOOGLE_REDIRECT_URI |
${PUBLIC_ORIGIN}/api/auth/google/callback |
Must match Google Cloud Console exactly |
Register the redirect URI in Google Cloud Console. http://localhost redirects are only accepted for local development.
Billing#
Plans, metering and key limits work without a payment provider. Plan switching is disabled until a provider is connected or you explicitly opt in.
| Variable | Default | Purpose |
|---|---|---|
BILLING_ALLOW_PLAN_SWITCH |
— | 1 allows plan changes without a provider, for demos or manual invoicing |
BILLING_MODE |
— | demo presents preview billing behaviour |
STRIPE_SECRET_KEY |
— | Reserved for the payment provider integration |
When EMAIL_WEBHOOK_URL is set, an email account must confirm its address before switching to a paid plan.
Payments (PayPal)#
Optional. Without credentials every payment route fails closed with 503 paypal_not_configured, and state.paypal.configured is false so the app hides the pay control. Amounts are rebuilt from the stored obligation and must be USD.
| Variable | Default | Purpose |
|---|---|---|
PAYPAL_ENV |
sandbox |
sandbox or live; picks the API base and the checkout host |
PAYPAL_CLIENT_ID |
— | REST app client id |
PAYPAL_CLIENT_SECRET |
— | REST app secret |
PAYPAL_PLATFORM_FEE_PERCENT |
10 |
Platform fee deducted from the captured escrow amount at release; the provider receives the net |
PAYPAL_WEBHOOK_ID |
— | Webhook id used to verify signatures at /api/paypal/webhook; without it events are acknowledged but not applied |
PAYPAL_ALLOW_WEBHOOK_SIMULATOR |
false |
Accept Developer Dashboard simulator transmissions (tagged sandbox_simulator); never enable in production |
PAYPAL_SDK |
on |
on uses the APIMatic server SDK for orders and authorize/capture; off forces REST |
PAYPAL_BASE_URL |
derived from PAYPAL_ENV |
Override the API base; tests only |
PAYPAL_TIMEOUT_MS |
15000 |
Per-request timeout for PayPal calls |
sandbox points at the PayPal sandbox APIs and checkout host. It is the default and the only mode this preview is exercised in. live uses the production APIs and moves real money; use separate credentials. Never mix sandbox and live credentials.
npm run dev copies only the PAYPAL_* lines from .env.local into the server process. The rest of that file is left alone, so a pulled production .env.local does not point local runs at the cloud database. Subscribe the webhook to PAYMENT.CAPTURE.* and PAYMENT.PAYOUTS-ITEM.* events.
Machine API#
| Variable | Default | Purpose |
|---|---|---|
MACHINE_RATE_LIMIT |
600 |
Requests per minute per machine key |
Counters live in workspace metadata, so the limit holds across instances sharing one database. Response headers x-ratelimit-limit and x-ratelimit-remaining report the state.
Marketplace and seller desk#
Bookings, receipts and the earnings ledger are stored per workspace. Payouts start as ledger entries; with PayPal configured, a seller payout is sent through Payouts to the email on file and tracked by batch id.
| Variable | Default | Purpose |
|---|---|---|
MARKETPLACE_FEE_BPS |
800 |
Platform fee in basis points (800 = 8%) recorded on each receipt and ledger entry |
SELLER_HOLD_DAYS |
3 |
Days a filed proof stays in held before the earning becomes available |
The fee is clamped to 0–3000 bps and the hold to 0–30 days. Payout requests also respect BLOCKED_COUNTRIES.
Region gating#
| Variable | Default | Purpose |
|---|---|---|
BLOCKED_COUNTRIES |
— | Comma-separated ISO 3166-1 alpha-2 codes denied new accounts, escrow movement and PayPal routes |
The country is read from x-vercel-ip-country, cf-ipcountry or x-country-code, in that order. Only set these behind a proxy you control: a client that reaches the server directly can forge them. Blocked requests receive 451 region_blocked.
Transactional email#
Password reset and email confirmation go through one HTTPS webhook that accepts { "to", "subject", "text" }. Point it at a Resend, Postmark or SES adapter.
| Variable | Default | Purpose |
|---|---|---|
EMAIL_WEBHOOK_URL |
— | Mail delivery endpoint; without it, reset and verify return 503 |
EMAIL_WEBHOOK_SECRET |
— | Signs requests as x-remindify-signature: sha256=HMAC(secret, "<timestamp>.<raw body>") |
The signature format matches execution connectors, so one verification helper works for both.
Execution connectors#
No variables are required to connect an executor; the URL and signing secret live in the agent passport. These tune the dispatcher.
| Variable | Default | Purpose |
|---|---|---|
EXECUTOR_TIMEOUT_MS |
8000 |
Per-attempt timeout |
EXECUTOR_ATTEMPTS |
3 |
Inline attempts per connector call, 1–5 |
EXECUTOR_RETRY_BASE_MS |
300 |
First backoff delay; later attempts back off from there |
EXECUTOR_ALLOW_LOCAL |
— | 1 permits http://localhost executor URLs; development and tests only |
Executor URLs must be HTTPS in production. Redirects are refused and DNS is pinned to the resolved address to reduce rebinding risk.
Durable retries and schedulers#
Transient failures that survive the inline attempts become durable outbox jobs. The local server sweeps them; serverless deployments must call the cron routes.
| Variable | Default | Purpose |
|---|---|---|
OUTBOX_MAX_ATTEMPTS |
5 |
Total delivery attempts before a job is marked failed |
OUTBOX_RETRY_BASE_MS |
60000 |
Backoff base for outbox retries |
OUTBOX_INTERVAL_MS |
30000 |
Local sweep interval |
OUTBOX_SECRET |
— | Bearer secret for GET/POST /api/cron/outbox |
CRON_SECRET |
falls back to OUTBOX_SECRET |
Bearer secret for GET/POST /api/cron/sweep |
curl -X POST https://your-app.example.com/api/cron/outbox \
-H "Authorization: Bearer $OUTBOX_SECRET"
curl -X POST https://your-app.example.com/api/cron/sweep \
-H "Authorization: Bearer $CRON_SECRET"Configure both on a schedule (Vercel Cron or any external scheduler). sweep walks every workspace; it takes a per-workspace lease so overlapping runs skip rather than duplicate, skips runs from the previous six hours and has a 20-second budget.
Trust layer#
Proof receipts work without any configuration: the server signs them with a receipt secret it generates and stores in workspace metadata. Set these to control the auditor and to keep the signing secret stable across deployments.
| Variable | Default | Purpose |
|---|---|---|
TRUST_RECEIPT_SECRET |
generated per workspace | HMAC-SHA256 key for receipt signatures; set the same value on every instance that shares a database |
GEMINI_API_KEY |
— | Enables AI capture and the Gemini proof auditor; without it both fall back to deterministic server-side rules |
AI_MODEL_ID |
gemini-2.5-flash |
Gemini model used for capture extraction and structured proof scoring |
AUDIT_MIN_CONFIDENCE |
0.8 |
Minimum confidence for an auditor verdict to count as verified |
CAPTURE_TIMEOUT_MS |
15000 |
A capture call slower than this falls back to the deterministic parser |
The auditor runs when a receipt is audited directly or when a release finds a receipt that is not yet verified. Without GEMINI_API_KEY, or when the Gemini call fails, the deterministic engine still checks the obligation amount, a confirmation or reference number, a date and the proof requirement. A provider failure is labelled deterministic_fallback so the receipt shows which engine decided. Capture uses the same key and falls back to the deterministic parser when the model is unavailable.
Escrow holds, capture and payouts use the PayPal variables above. Without PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET, a hold or release fails closed with paypal_not_configured; receipts and the auditor keep working.
Minimal configurations#
Local development — nothing required:
npm install
npm run devLocal with a stable origin for OAuth and PayPal returns:
PUBLIC_ORIGIN=http://localhost:4178
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=http://localhost:4178/api/auth/google/callback
PAYPAL_ENV=sandbox
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...Serverless production:
DATABASE_URL=postgres://...
PUBLIC_ORIGIN=https://your-app.example.com
EMAIL_WEBHOOK_URL=https://mailer.example.com/remindify
EMAIL_WEBHOOK_SECRET=...
OUTBOX_SECRET=...
CRON_SECRET=...
BLOCKED_COUNTRIES=KP,IR,SY,CU
PAYPAL_ENV=sandbox
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
PAYPAL_PLATFORM_FEE_PERCENT=10
PAYPAL_WEBHOOK_ID=...
GEMINI_API_KEY=...
AI_MODEL_ID=gemini-2.5-flash
AUDIT_MIN_CONFIDENCE=0.8
TRUST_RECEIPT_SECRET=...Then schedule /api/cron/outbox and /api/cron/sweep. Without a scheduler, executions still happen inline and retries queue but do not drain on their own.
Checking configuration#
GET /api/trust reports the active rail (PayPal mode, configured flag, hold days and fee percent) and the auditor (model, configured flag and threshold). GET /api/billing reports the current plan and usage. Never expose secret values in a health endpoint, a log line or an error message.