A safe public sandbox
DEMO_MODE=true turns an instance into a public sandbox that is safe
to expose to strangers: visitors get a fully seeded dashboard and API to
play with, while every outward-reaching adapter is forced to its mock at
the construction site — the demo can never email a human, charge a card,
submit an e-invoice IRN, deliver a webhook, or reach a SaaS, regardless
of what other environment variables are set.
This is what powers the “Open live demo” button on recurso.dev.
What visitors can do
Everything that makes billing worth demoing: create plans, customers, subscriptions, invoices, billable metrics, charges, wallets, alerts; meter usage; watch the ledger post. Test-mode only.What’s blocked
Identity and destructive edges answer403 {"code":"demo_mode"}: team
invites and role changes, SSO/MFA configuration, API-key rotation,
password resets, account changes, and registration.
Run it
:8080 + dashboard on :80. On boot the sandbox bootstraps a demo
tenant, the demo login, and the stable test key sk_test_12345, then
loads a rich data set — 40+ customers, 15 months of invoice history,
metering with graduated charges, a funded wallet, a commitment, and a
usage alert.
Entry & reset
POST /auth/demoopens a dashboard session as the demo user — the dashboard calls it automatically when visited with?demo=1, sohttps://your-demo-host/?demo=1lands visitors logged in. The endpoint only exists in demo mode (404 everywhere else).- Every
DEMO_RESET_INTERVAL(default1h) the environment wipes visitor changes and reseeds pristine data.
Next steps
Quickstart
Run the real thing locally
Going to production
Switch from demo data to live keys