DocsReferenceEnvironment

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, offchain 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, wallet sign-in messages, 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, produces mismatched wallet sign-in messages 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/password and wallet sign-in still work.

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.

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 are ledger entries only; no provider is connected.

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 and escrow movement

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
bash
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#

Preview mode works without any chain configuration. Add these only after contracts are deployed and verified. Every network has the same three variables: an RPC URL and the attestation and escrow contract addresses.

Network Variables
Base BASE_RPC_URL, BASE_ATTESTATION_CONTRACT, BASE_ESCROW_CONTRACT
Base Sepolia BASE_SEPOLIA_RPC_URL, BASE_SEPOLIA_ATTESTATION_CONTRACT, BASE_SEPOLIA_ESCROW_CONTRACT
Celo CELO_RPC_URL, CELO_ATTESTATION_CONTRACT, CELO_ESCROW_CONTRACT
Celo Sepolia CELO_SEPOLIA_RPC_URL, CELO_SEPOLIA_ATTESTATION_CONTRACT, CELO_SEPOLIA_ESCROW_CONTRACT

Defaults when a variable is unset:

Network Chain ID Default RPC
Base 8453 https://mainnet.base.org
Base Sepolia 84532 https://sepolia.base.org
Celo 42220 https://forno.celo.org
Celo Sepolia 11142220 https://forno.celo-sepolia.celo-testnet.org

Proof signing is offchain and works without any of these. Anchoring and escrow funding require the contract addresses; without them those routes report the network as unavailable.

Minimal configurations#

Local development — nothing required:

bash
npm install
npm run dev

Local with a stable origin for OAuth or wallets:

bash
PUBLIC_ORIGIN=http://localhost:4178
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=http://localhost:4178/api/auth/google/callback

Serverless production:

bash
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

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 networks and whether contracts are configured. GET /api/billing reports the current plan and usage. Never expose secret values in a health endpoint, a log line or an error message.