Demo Mode

Demo Mode transforms your VoxelSite installation into a self-guided, read-only showcase. Visitors see a real website at your root URL with an interactive Actions Bar, enter the Studio through a welcoming demo login page, and explore the visual editor, code files, forms, actions, assets, and settings — without being able to change anything.

The demo ships with pre-populated data for Code Editor, Notes, Board, Forms, Actions, Assets, Settings, and the Designs gallery. AI Chat and snapshot history show empty states — these surfaces use your real workspace data, which the demo intentionally does not expose.

This is not a stripped-down preview. It's a realistic product experience running against shipped demo fixture data, with every write action safely guarded.

Use cases

Live demo on your website. You sell VoxelSite as a product or use it as part of your agency offering. Embed a link to a VoxelSite demo installation on your portfolio or sales page so prospects can explore the tool at their own pace. Demo Mode ensures the installation stays intact no matter how many people click through it.

Showing a client the Studio before handover. You've built a site for a client using VoxelSite. Before giving them full access, you want them to see the Studio, understand the tools available, and review their site — without accidentally triggering an AI edit or publishing a change.

White-label demos. If you resell or white-label VoxelSite, Demo Mode lets your customers demo the product to their clients. The demo user is named "Studio Admin" — a neutral, professional name that works in any context.

Team review. You want a colleague or stakeholder to review your generated site and its structure before you continue iterating. They can browse freely without disrupting your work.

How it works

The demo preview site

When Demo Mode is active, your root URL (yourdomain.com/) serves a complete, styled website instead of the default VoxelSite placeholder. This is a pre-built demo site — a design agency portfolio with multiple pages — that ships with VoxelSite.

The demo site includes:

• Homepage — hero section, services overview, featured work
• Work — portfolio grid with category filters
• Services — detailed service descriptions
• Studio — about page with team information
• Contact — contact form with validation (submissions are blocked in demo mode)

All pages are fully styled and responsive. Images load from the shared assets directory, while CSS and JavaScript are inlined for maximum server compatibility (works on Apache, Nginx, Herd, and any PHP environment without special configuration). The Actions Bar appears at the bottom, allowing visitors to interact with demo forms.

The Studio

Inside the Studio, visitors can navigate every section:

• Code Editor — all site files visible and browsable in read-only mode, with system prompt files properly marked as protected
• Visual Editor — the live preview is interactive; visitors can select elements, open the inline source editor, explore the style panel, and switch between desktop, tablet, and mobile viewports
• Notes — 4 sample notes with markdown content, read-only editor, preview and send-to-chat still functional
• Board — pre-populated kanban board with cards across all three columns; fully interactive (drag-and-drop, expand cards, explore forms) but changes are not saved
• Assets — a gallery of curated demo images plus CSS/JS code files
• Forms — a contact form with realistic demo submissions (names, emails, messages across multiple statuses)
• Actions — two configured actions with fields, validation rules, and submission records
• Settings — site identity, AI provider selection, and notification settings (no real API keys are shown)
• Team — demo team members with different roles (owner, editor, viewer)

The Actions Bar

The Actions Bar — the floating form bar at the bottom of VoxelSite websites — appears in both the Studio's preview iframe and the public demo site at your root URL. Visitors can open action forms, fill them in, and submit — but submissions go to a safe demo stub that returns a success response without writing any data.

On the root demo site, the bar detects the demo context automatically and routes requests through the Studio API. No special configuration is needed.

Enabling Demo Mode

Create a file named .demo in your VoxelSite project root (the same directory as index.php and _studio/):

touch /path/to/your-site/.demo

An empty file activates Demo Mode with default behavior — all demo indicators visible. No restart, no configuration change, no build step.

The file may optionally contain key=value pairs (one per line) to configure demo presentation:

# Screenshot mode — hide all demo indicators
hide_banner=true

See Hiding demo indicators for details.

To disable Demo Mode, delete the file:

rm /path/to/your-site/.demo

The .demo file is automatically excluded from Git via .gitignore.

[!IMPORTANT] The .demo file is an installation-wide switch. When it exists, the entire installation operates in demo mode — not just the Studio. This means:

• All Studio API write operations are blocked (POST, PUT, DELETE)
• All form submissions via submit.php are blocked with a 403 response
• The root URL serves the demo preview site (if the default index.php is in place)

If you enable .demo on a site that is still published with live forms, those forms will stop accepting submissions immediately. Always unpublish before enabling Demo Mode.

If your site is currently published

When you publish a site with VoxelSite, the AI-generated index.php replaces the default one. This AI-generated file does not include the demo routing code, so the demo preview site at the root URL won't appear and live form submissions will be silently blocked.

To fix this, unpublish your site first:

1. Open VoxelSite Studio
2. Click the chevron on the Publish button (bottom-right status bar)
3. Select Unpublish
4. Then create the .demo file

Unpublishing restores the default index.php, which includes demo detection. Your preview workspace, snapshots, files, and settings are all preserved — unpublishing only takes the live site offline.

Your work is safe. Unpublishing doesn't delete anything. All your pages, conversation history, and design snapshots remain exactly as they were. When you remove the .demo file and re-publish, your site comes back exactly as it was.

What's visible vs. what's blocked

The login page

By default, the login page transforms into a welcoming demo entry point:

• Title changes to "Welcome to the Demo" with an inviting subtitle
• A warm "Demo Mode" banner explains the read-only nature
• Email and password fields are pre-filled with the demo credentials
• The submit button reads "Enter Demo" instead of "Open Studio"
• The "Forgot password?" link is hidden (not relevant in a demo)

When hide_banner=true is set, the login page looks like a normal Studio login — empty fields, standard "Open Studio" button, Forgot link visible. The demo credentials still work.

Inside the Studio

• By default, a persistent "DEMO" badge appears in the top navigation, so visitors always know they're in a demo. When hide_banner=true is set, the badge is hidden.
• The demo user is shown as "Studio Admin" — a professional, generic name suitable for any context.

Interactive elements (visible but guarded)

Demo Mode prioritises showing the product, not hiding it. Several interactive elements are fully visible — visitors can open modals, explore form fields, and see confirmation dialogs — but the actual write action is guarded:

What's blocked

All state-changing API requests are rejected at the server level:

What's allowed

All read operations work normally:

• Browsing the demo preview site at the root URL, navigating between pages
• Entering the Studio through the demo login page
• Browsing pages in the preview, switching between desktop/tablet/mobile viewports
• Navigating through the visual editor, selecting elements, opening the inline source editor, editing styles (without saving)
• Opening files in the code editor (read-only mode is enforced automatically)
• Browsing uploaded assets in the gallery view
• Viewing form submissions and their details
• Browsing notes, previewing markdown, and sending note content to chat
• Browsing the kanban board, expanding cards, and exploring the editing UI
• Viewing action configurations and records
• Opening modals — reference URL, publish, unpublish, settings panels
• Viewing settings (API keys are encrypted — never exposed)
• Switching between light and dark themes
• Using keyboard shortcuts for navigation

Backend enforcement

Demo Mode is enforced at the API level, not just the UI. Even if someone bypasses the frontend guards (e.g., by sending API requests directly via curl or the browser console), the server rejects all POST, PUT, and DELETE requests with a 403 response and a demo_mode error code.

The only exceptions are:

• POST /auth/login — visitors need to enter the demo
• POST /auth/logout — visitors need to leave the demo
• POST /agentic/demo-submit — the safe stub for the preview Actions Bar

This means Demo Mode is safe to expose publicly. The backend guarantees that no data can be modified, regardless of how the request is made.

Setting up a demo

Step 1: Generate a site

Before enabling Demo Mode, generate a complete site so visitors have something to explore. An empty Studio isn't much of a demo. Use a clear, specific prompt:

Build a website for Studioform, a brand and digital design practice

Step 2: Prepare the demo data

The demo ships with built-in fixture data for forms (contact form with 4 submissions), actions (consultation booking + quote request with records), notes (4 sample notes with markdown content), board (kanban cards across all columns), assets (curated gallery images), settings, and team members. These appear automatically — no manual setup needed.

Note: The AI Chat and Designs (snapshots) sections show empty states in demo mode. These surfaces use your real workspace data, which the demo intentionally does not expose. Notes shows sample data but is read-only. Board shows sample data with full interactivity but no persistence.

Step 3: Unpublish (if published)

If you've published the site to your live domain, unpublish it first. This restores the default index.php which includes the demo preview routing.

Step 4: Enable Demo Mode

touch /path/to/your-site/.demo

Step 5: Verify

1. Visit your root URL — you should see the demo preview site with the interactive Actions Bar
2. Navigate to /_studio/ — you should see the demo login page
3. Click "Enter Demo" — you should enter the Studio with demo data visible in Code Editor, Forms, Actions, Assets, Settings, and the Designs gallery
4. Note that AI Chat and snapshot history show empty states — this is expected (these sections use your real workspace data, which the demo does not expose)
5. Open Notes — you should see 4 sample notes with a "Read-only" indicator and no editing controls
6. Open Board — you should see a kanban board with sample cards; try dragging cards and expanding them
7. Try to send an AI prompt — you should see a friendly "not available in demo" toast
8. Try submitting the contact form on the root demo site — you should see a "Demo Mode" notice instead of a submission

Demo credentials

Demo Mode uses hardcoded credentials:

• Email: [email protected]
• Password: welcome3210

These are pre-filled on the demo login page. The demo session bypasses real authentication — no actual user account with these credentials needs to exist. Your real owner account continues to work normally alongside demo sessions.

The real owner can log in at any time by clearing the pre-filled fields and entering their own credentials. When logged in with real credentials while Demo Mode is active, you see and work with your real workspace as usual.

Data isolation

Demo Mode uses its own fixture data for all surfaces. The Studio reads from shipped demo data — not your real workspace. This means:

• Your live files are never exposed to demo visitors
• Your real AI conversations are not visible
• Your API keys are never shown (demo settings use placeholder values)
• Your form submissions are not visible (demo submissions are fixtures)

The only shared resources are:

• Images and fonts in the /assets/ directory — these are referenced by both the live site and the demo preview
• The VERSION file — so the demo shows the correct VoxelSite version

Real owner login still works alongside demo sessions. If you log in with your real credentials while Demo Mode is active, you see and work with your real workspace as usual.

Server compatibility

The demo preview site works on any PHP-capable server:

• Apache — works out of the box (.htaccess handles routing)
• Nginx (Forge, RunCloud, Ploi, Herd) — works out of the box (demo CSS/JS are inlined, no special static file rules needed)
• Shared hosting — no command-line access needed, just create the .demo file via your file manager

No special server configuration, symlinks, or directory permissions are required beyond what a normal VoxelSite installation needs.

Removing Demo Mode

Delete the .demo file:

rm /path/to/your-site/.demo

The change is instant — no restart, no cache clearing needed. The root URL returns to the normal VoxelSite behavior (default placeholder or your published site), and the Studio login page returns to the standard login form.

Hiding demo indicators

For clean screenshots, recordings, or white-label presentations, you can hide all demo-specific visual indicators while keeping demo mode fully active.

Add hide_banner=true to your .demo file:

hide_banner=true

This hides:

• The DEMO badge in the Studio top navigation bar
• The "Welcome to the Demo" login title, "Demo Mode" banner, and pre-filled credentials

Everything else stays the same — all read-only enforcement, fixture data, write blocking, and demo authentication continue to work. The hide_banner option only affects visual presentation.

To restore the banners, remove the line from .demo or set hide_banner=false.

Related

• Publishing — how publishing works and the publish/unpublish lifecycle
• Actions — the Actions Bar and AI agent integration that demo visitors can explore
• Forms — form submissions visible in the demo
• Notes — private scratchpad visible in the demo
• Board — kanban task tracker interactive in the demo
• Settings — settings visible in the demo
• Team — team members visible in the demo