![\"npm](\"https://img.shields.io/npm/v/sporades.svg\")
\n ![\"npm](\"https://img.shields.io/npm/dm/sporades.svg\")
\n ![\"MIT](\"https://img.shields.io/npm/l/sporades.svg\")
\n ![\"GitHub](\"https://img.shields.io/badge/GitHub-mgscox%2Fsporades-181717?logo=github\"){kind=icon}
\n\n \n \n =22.13 <23 or >=24\" src=\"https://img.shields.io/badge/node-%3E%3D22.13_%3C23_%7C_%3E%3D24-339933?logo=node.js&logoColor=white\">\n
\n
\n [npm package]\n
\n\nDesigned as Agents-first, Sporades is a CLI-first platform for building, running, inspecting, and hosting\nsmall full-stack web Capsules supporting vanilla Typescript, React, Preact, Inferno, Lit, SolidJS, Vue, and Svelte \nfor front-end clients.\n\nIt is intended for developers and coding Agents who want deterministic commands\ninstead of dashboards: scaffold a Capsule, run it locally, test the bundled\nruntime in Docker, then publish it to a private or cloud Host server.\n\n```sh\n# install sporades globally\nnpm install -g sporades\nsporades -h\n```\n\nCreate a 'todo' app and spin-up a live-refresh dev server, a staging server on local docker service, and deploy to a remote production server:\n\n```sh\nsporades create notes --template todo\ncd notes\nsporades dev\nsporades deploy\nsporades host push --restart\n```\n\n## Why Sporades?\n\n- **One command loop for humans and agents**: create, run, inspect, deploy, and\n repair Capsules from the terminal.\n- **Full-stack without the usual wiring**: server schema, queries, mutations,\n auth, file uploads, custom endpoints, app messages, and browser hooks live\n behind a small authoring API.\n- **Same bundle everywhere**: Dev sessions, local Docker Container sessions, and\n Hosted Capsules all run the same bundled server and client output.\n- **Private-host friendly**: Host servers use boring, inspectable pieces:\n Docker, Caddy, Node, SQLite, filesystem storage, and SSH.\n- **Agent-operable by default**: structured JSON output, actionable error hints,\n logs, database inspection, and non-interactive commands are first-class.\n- **Comprehensive SDK**: built-in authentication, database, user preferences,\n and storage.\n- **Named automation without fake users**: linked users can issue scoped Access\n keys for API clients while Capsule code retains the real owner in `ctx.auth`\n and distinguishes named API access through `ctx.credential`.\n- **Built-in collaboration, explicitly authorized**: runtime-owned Teams,\n email-bound Join links, membership application roles, and explicit Team ACL\n decisions—without a hidden current Team or automatic data partitioning.\n Trusted `teams.admitJoin` policies may make atomic seat decisions from\n read-only app state hidden by the joining user's ordinary row ACLs and the\n exact Team's provider-free verified billing projection.\n- **Headless Team Billing, app-rendered**: an optional `teamBilling` declaration\n binds stable product keys to exact sandbox/live Stripe Prices and a fixed or\n accepted-Team-member quantity policy. Sporades rechecks current Team-admin\n authority plus the Capsule's transaction-bound policy on every operation and\n exposes the closed, provider-free `teamBilling.get(teamId)` projection plus\n durable `teamBilling.startCheckout(...)`, `teamBilling.openPortal(...)`, and\n `teamBilling.requestPlanTransition(...)`. Portal owns compatible same-policy\n switches; Sporades manages fixed-to-Team-counted transitions and keeps a\n Team-counted Subscription converged after membership commits.\n `teamBilling.prepareErasure(...)` durably expires or safely resolves every\n issued Checkout and immediately cancels known or newly discovered live\n Subscriptions before a transaction-bound server admission permits the app's\n separate local deletion. Provider-free identity tombstones reject late\n entitlement recreation; the Stripe Customer is not deleted.\n Those commands may return only validated, short-lived Stripe-hosted URL\n capabilities. Verified Checkout, Subscription, and failed-invoice evidence\n converges through runtime-owned semantic ratchets and terminal latches;\n malformed or ambiguous evidence fails closed without exposing provider\n identifiers. The Capsule owns every component, route, message, and\n entitlement decision.\n Offline migration tools can import complete verified legacy snapshots and\n provider-free replay guards through `sporades/server/team-billing-import`;\n the seam performs no provider I/O and rejects incomplete or changed tuples,\n including corrupted durable Event ordering or terminal-latch state.\n- **Realtime everything**: configuration free - automatic notifications, even for Postgress and AWS-S3\n\n## Documentation\n\n- [User guide](https://mgscox.github.io/sporades/user-guide): build, run, inspect, deploy, auth,\n preferences, files, endpoints, messages, and common workflows.\n- [Feature reference](https://mgscox.github.io/sporades/guide/reference): exhaustive contracts and\n command lookup, split into focused topic pages.\n- [Built-in Teams](https://mgscox.github.io/sporades/reference/teams): collaboration model, Join\n links, application roles, explicit Team ACL decisions, and the headless Team\n Billing declaration and safe projection.\n- [Access-key server and operator reference](https://mgscox.github.io/sporades/reference/server-runtime#gate-handlers-with-requireauth):\n scoped Bearer admission, user-owned lifecycle, Credential provenance, and\n the bounded operator CLI.\n- [LLM documentation manifest](https://mgscox.github.io/sporades/llms.txt): release-matched Markdown\n sources for agents and other documentation tools.\n- [Architecture](https://mgscox.github.io/sporades/architecture): platform model, runtime modes, Host\n server design, and ownership boundaries.\n- [Runtime layout](https://mgscox.github.io/sporades/runtime-layout): generated files, mounts, Host\n directories, and persistent data locations.\n- [Host server installation](https://mgscox.github.io/sporades/server-installation): prepare a Linux Host\n server for Hosted Capsules.\n- [Product requirements](https://mgscox.github.io/sporades/PRD): implemented scope, deferred scope, and\n core product principles.\n- [Roadmap](https://mgscox.github.io/sporades/ROADMAP): candidate features and promotion status.\n\n## A Tiny Capsule - the entire server code for a real-time 'to-do' app\n\n```ts\n// Everything we need comes from Sporades server SDK\nimport {\n Boolean,\n String,\n capsule,\n mutation,\n query,\n table,\n} from \"sporades/server\";\n\nexport default capsule({\n name: \"notes\",\n\n // tables automatically get createdAt, createdBy, and a unique Id\n schema: {\n // tables can have optional ACL - default is \"open to all\"\n todos: table({\n text: String(),\n done: Boolean().default(false),\n ownerId: String(),\n }),\n },\n\n // queries are automatically write-through cached on the server\n queries: {\n // all todo entries for current user (anonymous by default)\n todos: query((ctx) =>\n // context 'ctx' contains user, db, storage, auth, etc.\n ctx.db.todos\n .where(\"ownerId\", ctx.auth.userId)\n .orderBy(\"createdAt\", \"desc\")\n .all(),\n ),\n },\n\n mutations: {\n addTodo: mutation((ctx, text: string) =>\n ctx.db.todos.insert({ text, ownerId: ctx.auth.userId }),\n ),\n },\n});\n```\n\nClient scaffolds wire `sporades/client` into React or Preact hooks, Vue\ncomposables, Svelte stores, SolidJS signals, Lit reactive controllers, native Inferno lifecycle adapters, or framework-neutral subscriptions\nso the UI can consume queries, mutations, and auth without hand-rolled fetch plumbing.\n\n## What You Get\n\nSporades currently includes:\n\n- React, Preact, and Vue project scaffolds with `blank`, `todo`, `guestbook`,\n `photo-library`, and `campfire` templates. Vue uses native Single-File\n Components; Campfire is the complete consented User journey tracker exemplar.\n- Svelte/Vite project scaffolds across the complete template set, with native\n components and lazily observed stores. Campfire preserves identity-safe\n consent, caller-renewed Journey TTL state, and deterministic cleanup.\n- SolidJS/Vite scaffolds across the complete template set, with native JSX,\n signals, identity-safe Campfire consent, and reactive-root cleanup.\n- Lit/Vite Web Component scaffolds across the complete template set, with\n component styles and host-lifecycle reactive controllers. Campfire preserves\n serialized identity-safe consent, explicit Journey TTLs, and cleanup.\n- Inferno scaffolds across the complete template set, using native class-component\n lifecycle and classic Inferno JSX without React compatibility packages. esbuild\n remains the default; Vite is available explicitly with full-page Dev refresh.\n- Every new blank Capsule includes a built-in but disabled Stripe payment\n foundation: server-owned wiring, named Checkout and Customer Portal Jobs, shared Job state, an\n empty Price catalogue, and no credentials, payment UI, active callback route, or\n browser Stripe SDK. Complete activation supports an authorized, idempotent\n one-time or recurring subscription Checkout through the same durable Job,\n actor-scoped progress, safe retries, and validated Stripe-hosted redirects.\n Portal remains linked-user-only: Capsule policy authorizes an opaque billing\n holder and resolves its existing Customer before enqueue, then the Job repeats\n both checks before provider access so revocation fails safely. No Customer\n identity is stored in the Capsule intent or Job payload. It is the preferred\n surface for ordinary customer-managed payment methods, invoices,\n cancellations, and supported subscription changes. Complete activation also\n registers one collision-checked callback path. Signed exact bytes are admitted\n into one idempotent Privileged Job per Stripe Event before acknowledgment;\n retries converge and no Capsule billing state changes automatically. The Job\n delivers one Verified Stripe event to the blank Capsule's single\n `stripeEvents: stripeEvent(...)` policy seam under the userless Privileged\n audit lifecycle. Capsules that need one serialized, all-or-nothing database\n consequence can opt into `stripeEvent({ consequence: \"atomic\" }, handler)`;\n the legacy declaration remains available for cooperative long-lived handlers.\n Generated policy ignores unknown events and tells authors to\n make deliberate consequences idempotent and order-independent, reject stale\n later-arriving observations, and avoid logging or retaining raw provider data.\n A successful reserved Stripe Event Job retains its verified payload for 30\n days, then bounded runtime cleanup leaves only the digest-backed terminal\n replay tombstone. Unresolved deliveries retain their retry/repair payload;\n this includes legacy successes with absent or malformed completion timestamps,\n plus canonical near-ceiling settlements whose exact deadline is\n unrepresentable. Safe operator inspection distinguishes those cases without\n exposing provider data.\n The catalogue owns each Price mode; browser input owns neither mode nor Stripe\n identity. Existing and non-blank Capsules remain unchanged.\n- Local Dev sessions with rebuilds, WebSocket reconnects, SQLite persistence,\n logs, database inspection, auth helpers, and file storage. Every admitted\n esbuild/Vite pair uses the same acknowledged Sporades full-page refresh\n protocol after a successful client rebuild; no pair promises HMR.\n- Local Docker Container sessions for production-like staging tests.\n- Hosted Capsules on SSH-reachable Host servers, routed through Caddy and run in\n hardened Docker containers.\n- A [standalone trace stack](monitoring/trace/README.md), generated by `sporades monitoring stack init --dir