Demo / Sandbox Mode

Demo mode turns a deployment into a public sandbox: anyone can click and edit the page without a password, and every visitor gets their own isolated copy of the content. It’s how the live demo works — try it, edit a headline, and your changes stay private to your browser.

Not for a real editable site

Demo mode treats every visitor as an editor (no password) and is meant for a throwaway “try it” deployment. Don’t enable it on a site you actually publish from — use the normal password + session model there.

What it does

When CARET_DEMO_MODE=true:

• The middleware mints a caret_demo_session cookie on first request (2-hour sliding window) and treats that visitor as an authorized editor — no login, no shared password.
• Every write goes to a per-session overlay layered over the shared base content. Reads return base content plus that session’s own edits; deletes are tombstoned in the overlay.
• Sessions never see each other’s edits, and the canonical base content is never mutated by visitors. When a session’s cookie expires (or the visitor closes the tab), their sandbox is gone.

Requirements

Cloudflare only

Session isolation needs a storage adapter that implements makeSessionOverlay and an upload handler that implements makeSessionWrapper. Today only the Cloudflare adapters do — cloudflareStorage (KV) and r2Uploads (R2).

The filesystem and in-memory adapters don’t, so with CARET_DEMO_MODE=true on those, the integration falls back to the shared adapter: every visitor edits the same content with no isolation. That’s not a safe public sandbox. Deploy demo mode on Cloudflare Workers.

Enabling it

1. Deploy on Cloudflare Workers with KV + R2, following Deployment → Cloudflare Workers.

2. Set CARET_DEMO_MODE as a Worker variable.

   wrangler.toml

   [vars]
   CARET_DEMO_MODE = "true"

   No editor password is required in demo mode, but you can still set CARET_SESSION_SECRET for signed cookies.

3. Seed the starting content. Demo sessions overlay whatever is in your base store. Commit starter entries to .caret/data/ so the bundled fallback seeds KV, or write them in once. Every visitor begins from this snapshot.

Upload quotas

To keep a public sandbox cheap and abuse-resistant, demo uploads are capped per session. Defaults are 5 MB per file and 25 MB per session; tune them on r2Uploads():

astro.config.mjs

import { r2Uploads } from '@caretcms/cloudflare';

r2Uploads({
  binding: 'CMS_R2',
  sandboxPerFileBytes: 5 * 1024 * 1024,     // default: 5 MB
  sandboxPerSessionBytes: 25 * 1024 * 1024, // default: 25 MB
})

A visitor who exceeds the per-file cap gets File too large (5MB max in sandbox); exceeding the session cap gets Sandbox storage full — close this tab to start a fresh session. These limits apply only in demo mode — normal deployments upload without them.

How a session is isolated

Layer	In demo mode
Auth	A caret_demo_session cookie stands in for the editor session; no password check
Storage	SessionOverlayAdapter wraps your base adapter — reads merge base + overlay, writes hit the overlay, deletes tombstone
Uploads	QuotaUploadHandler wraps your upload handler with per-file / per-session byte caps
Lifetime	2-hour sliding TTL on the cookie; no persistence guarantees

Next steps

Deployment Stand up the Cloudflare Workers + KV + R2 deploy demo mode needs.

Storage Adapters Why demo mode requires the Cloudflare adapters.

Authentication & Security The normal password-based model for real sites.