Workspace Architecture

Last updated: June 1, 2026

How a WebSandbox workspace is structured — its file system, lifecycle, state management, and relationship to your account.

What is a Workspace?

From the platform's perspective, a workspace is a record in your account database that references:

• A unique workspace ID used to scope all associated IndexedDB data
• A template type (blank, React, Next.js, etc.) used on first boot
• A metadata blob (name, description, thumbnail, created/updated timestamps)
• An optional git remote URL if the workspace is linked to a repository

File System Structure

For Instant Projects, the virtual file system inside a WebContainer mirrors a standard Unix directory layout mounted in-browser. For Cloud Servers, this mirrors a real disk volume on a VM. In both cases, WebSandbox mounts your project at the root:

/
├── node_modules/     ← npm dependencies (not persisted to IndexedDB)
├── src/              ← your application source
├── public/           ← static assets
├── .git/             ← git object store (persisted with binary encoding)
├── package.json
└── ...

For Instant Projects, node_modules/ is excluded from the IndexedDB snapshot — it is reinstalled on each boot via npm install to keep the snapshot size manageable. Cloud Servers persist node_modules/ naturally on the VM's disk volume.

Workspace Lifecycle

A workspace moves through distinct lifecycle phases, which differ slightly by platform:

1. Created — the workspace record is written to your account; template files are populated.
2. Booting — on open, the WebContainer initialises (Instant Projects) or the VM provisions and mounts the file system (Cloud Servers).
3. Active — the dev server is running, the editor is ready, and changes are being written to IndexedDB (Instant) or the network volume (Cloud).
4. Suspended / Hibernating — the browser tab is hidden or closed. Instant Projects suspend immediately and preserve state in IndexedDB. Cloud Servers hibernate after inactivity to save compute resources while preserving disk state.

State Management

WebSandbox uses a layered state architecture for Instant Projects:

• FileRepositoryContext — a React context that ensures consistency between the editor, the WebContainer FS, and IndexedDB.
• Dexie (IndexedDB) — the persistent store keyed by workspaceId + path.
• WebContainer FS — the ephemeral in-memory layer synced by the FileRepository.

For Cloud Servers, state management is much simpler: files are written directly to the persistent remote file system via the VSCode Server connection, completely bypassing IndexedDB.

Workspace Isolation

Each workspace is completely isolated from every other workspace:

• Data Isolation: Instant Projects use namespaced IndexedDB databases. Cloud Servers use isolated VMs and distinct network volumes.
• Network Isolation: WebContainer network stacks are scoped to a Service Worker registration. Cloud Server ports are securely forwarded only to authenticated users.
• Editor State: Open tabs and cursor positions are stored per-workspace in localStorage regardless of the runtime.