Demo mode

Enable Demo Mode on a demonstration installation to let visitors browse Studio with sample content. The demo blocks saved changes and AI generation; some controls simulate a result.

The demo uses sample data for Code Editor, Notes, Board, Forms, Actions, Assets, Settings, and the Designs gallery. Conversation and snapshot history start empty; the demo does not expose the installation’s real history.

Use a separate installation for demonstrations. Check the enabled views and write restrictions below before sharing its URL.

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 blocks saving changes through the Studio.

Showing Studio before handover. Use a separate demo installation to show the controls before granting an account on the client site.

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 functional category filters
• Services - detailed service descriptions
• About - studio information and team philosophy
• Contact - contact form with validation (submissions are blocked in demo mode)

The demo pages use shared images and inline CSS and JavaScript. The Actions Bar lets visitors try the sample forms. Check the demo on your server before sharing its URL.

The studio

Inside Studio, visitors can inspect these sections:

• Code Editor - browse the demo files in read-only mode; system prompts show a protected marker
• Site - the structural graph explorer shows indexed pages, partials, routes, tokens and assets with impact queries; reads live site structure without applying edits
• 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 sample submissions
• 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)

Illustrative settings

The maintained demonstration shows a sample built-in AI configuration so Chat opens at its ready-to-start screen. Conversation history is still empty, and sending a prompt remains blocked.

Settings → Connections shows an explicitly labelled sample connection, an inert example.invalid endpoint and illustrative successful request history. No real credential is revealed, no external client is connected, and these fixtures do not establish client qualification. Interrupted changes shows a healthy empty state with no retained operation needing attention.

These are read-only demonstration fixtures, not access to the installation’s real connection or recovery records. They describe the maintained demo; an earlier release archive may show different sample states.

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 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 return a demo restriction.

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.

Unpublish removes published pages from the live root. Preview pages, conversations and snapshots remain. Remove .demo, check the preview and publish to put the site online again.

What's visible vs. what's blocked

The login page

By default, the login page shows:

• 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, to identify the 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)

Visitors can open these controls. Demo guards block or simulate their write actions:

What's blocked

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

What's allowed

Demo visitors can inspect these views:

• 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 submissions
• Opening modals - reference URL, publish, unpublish, settings panels
• Viewing settings with placeholder API-key values
• Browsing the Site workspace - page tree, hierarchy diagram, entity browser, impact analysis, blast radius queries, and exploring the Move, Rename, and Delete panels (write actions show demo toasts)
• Switching between light and dark themes
• Using keyboard shortcuts for navigation

Backend enforcement

The server rejects POST, PUT and DELETE requests with HTTP 403 and code demo_mode, except for the routes below. Frontend changes cannot bypass that check.

The native demo routes allow only these exceptions:

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

Private Studio MCP access and administrative changes are blocked in demo mode. The public demo forms use a no-write stub; they do not prove delivery or business-record storage.

Test the demonstration in a separate installation before sharing it. Keep real customer content and credentials out of the demo.

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 sample submissions), notes (4 sample notes with markdown content), board (kanban cards across all columns), assets (curated gallery images), settings, and team members. Demo GET handlers supply these fixtures.

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. Open /_studio/ and check 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 can still authenticate while demo mode is active. The global write restriction remains in place.

Clear the pre-filled demo credentials to sign in with your real account. Remove .demo before editing the installation.

Data isolation

Several demo views use bundled fixture data. The Site workspace can read live site structure, and the demo shares website assets. Use a separate demonstration installation and check what each view exposes:

• Site structure and shared assets may be visible in the demo
• Your real AI conversations are not visible
• Demo API-key fields use placeholder values
• Your form submissions are not visible (demo submissions are fixtures)

Shared resources include:

• 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. Remove .demo before returning to normal editing with your real account.

Server compatibility

The demo preview uses the same PHP server as your VoxelSite installation:

• 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 - create the .demo file through your hosting 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 next request detects the removed file; no restart is required. 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