How WebSandbox Works

Last updated: June 1, 2026

A high-level architectural overview of the WebSandbox platform — from browser request to running application.

Architecture Overview

At the highest level, WebSandbox has three major subsystems running simultaneously in the browser:

• The Runtime Layer — an execution environment powered either by a WebContainer instance (booting a full POSIX OS in WebAssembly for Instant Projects) or a dedicated virtual machine/container (for Cloud Servers)
• The Persistence Layer — an IndexedDB-backed store (using Dexie) that serialises your file system and git state so workspaces survive page refreshes
• The Editor Layer — powered by CodeMirror for Instant Projects (running entirely in the browser) and VSCode Server for Cloud Servers (VM-based), giving you real IntelliSense and a robust development environment

The Boot Sequence

Every time you open a workspace, the boot sequence dynamically adapts to the project type:

Instant Projects (Browser-based)

1. Service Worker activation — intercepts all page requests and injects COOP/COEP headers.
2. File system rehydration — project snapshot is read from IndexedDB via FileRepositoryContext.
3. WebContainer boot — initialises the WASM runtime and mounts the file tree.
4. Language server launch — the TypeScript LSP process starts inside the container.
5. Dev server start — auto-executes start or dev npm scripts.
6. Preview activation — the container emits a server URL proxied through the Service Worker.

Cloud Servers (VM-based)

1. Infrastructure provisioning — a VM or container is securely allocated on the backend.
2. Volume mounting — your persistent network volume containing the project files is mounted.
3. VSCode Server boot — initializes the backend language services and extension host.
4. Connection establishment — a secure WebSocket tunnel is formed between your browser and the remote server.
5. Dev server start — remote npm scripts are executed and ports are dynamically forwarded to your browser.

The Persistence Layer

For Instant Projects, the file system is ephemeral. WebSandbox solves this with a bidirectional synchronisation mechanism between the virtual FS and IndexedDB. Every file write in the editor triggers a debounced serialisation to the Dexie database.

For Cloud Servers, your files live on persistent network volumes attached directly to the VM, guaranteeing robust file retention natively without the need for browser storage syncing.

The Preview Pipeline

The live preview uses a sandboxed <iframe> that securely routes traffic based on your runtime:

• Instant Projects: Dev servers bind to a virtual port (e.g., localhost:3000). The Service Worker intercepts requests to that origin and routes them through the WebContainer network emulation layer.
• Cloud Servers: A secure tunnel forwards remote VM ports over WebSockets directly to the browser, making the remote server appear as if it is running on your local machine.

Security Boundaries

Each WebContainer is scoped to its Service Worker origin. A script running in one workspace cannot access the file system of another workspace. The WASM sandbox further restricts syscalls — there is no access to the host operating system, network interfaces, or file system beyond the virtual FS exposed by the WebContainer API.

For a deep dive into the security model, see Security Model.