diff --git a/sites/browserpod/public/assets/Browserpod-diagram_2.webp b/sites/browserpod/public/assets/Browserpod-diagram_2.webp
new file mode 100644
index 00000000..e2ecd526
Binary files /dev/null and b/sites/browserpod/public/assets/Browserpod-diagram_2.webp differ
diff --git a/sites/browserpod/src/content/docs/00-overview.mdx b/sites/browserpod/src/content/docs/00-overview.mdx
index 29274365..f0693d0a 100644
--- a/sites/browserpod/src/content/docs/00-overview.mdx
+++ b/sites/browserpod/src/content/docs/00-overview.mdx
@@ -1,14 +1,13 @@
---
title: BrowserPod
shortTitle: Overview
-description: Run sandboxed backend services directly in a client browser's tab.
+description: A universal execution layer for running code safely in the browser
---
import LinkButton from "@leaningtech/astro-theme/components/LinkButton.astro";
import { DISCORD_URL } from "@/consts.ts";
-
+
-**BrowserPod** is a **sandbox API**. It provides in-browser runtimes for common backend languages, libraries and frameworks.
-Instead of provisioning a cloud server, BrowserPod's API enables a client browser to host full runtimes compiled to WebAssembly (Wasm), running at native speed.
+**BrowserPod** is a universal execution layer for browser-based compute. It provides a sandboxed runtime API that enables client browsers to host full runtimes, compiled to WebAssembly (Wasm), with near-native performance.
+
+Instead of provisioning costly cloud servers, BrowserPod allows you to execute full-stack workloads directly within the user's browser tab. Each **pod** is ephemeral, constrained by the browser's security model, and isolated from the host operating system via a dedicated syscall layer.
[Get started](/docs/getting-started/quickstart) · [Basic
@@ -39,46 +39,46 @@ Instead of provisioning a cloud server, BrowserPod's API enables a client browse
[Licensing](/docs/more/licensing)
-BrowserPod is ephemeral by design. Each **pod** (_see [pod](/docs/more/glossary#pod)_) runs inside a browser tab and ends when the tab closes or reloads. Because BrowserPod runs inside the browser, each Pod is constrained by the browser’s security model, isolated from the user’s OS, with limited access (via syscalls) to local files or system resources unless you explicitly provide it.
+## The Shift: Moving Compute to the Client
+
+Traditional sandboxed environments rely on cloud-side virtualization. While effective, this model introduces recurring infrastructure costs, network latency, and data privacy complexities.
+
+**BrowserPod flips the economics of code execution.** By leveraging the user's local CPU and the browser's security model, you eliminate per-session infrastructure overhead. This makes it financially viable to scale applications, like AI code interpreters or interactive coding platforms, to millions of users without the linear growth of a cloud bill.
+
+## Use Cases
-At a high level, BrowserPod gives you:
+### **Development Tools & Interactive Content**
-- A **backend runtime** running in the browser (e.g., Node.js, Python, Ruby)
-- A **Linux‑like virtual filesystem** for files and folders
-- **Portals** that can expose local servers at public URLs
+BrowserPod is built to power the next generation of web-based IDEs and full-stack development environments. By supporting package installs, dev servers, and build tools with high fidelity, it allows developers to create "real" workflows in the browser. This extends to documentation and live demos, where you can turn static examples into runnable environments that users can modify and execute without leaving the page.
-Everything runs client‑side within the browser sandbox, so users don’t need to install anything.
+### **Safe Execution of Untrusted Code**
-## What you can do with BrowserPod
+Whether you are running AI-generated code, user scripts, or agent-assembled programs, BrowserPod provides a secure sandbox with zero "cold start" latency. Because execution happens on the client side, you tighten security boundaries by keeping sensitive data within the user's local environment.
-- **Execute AI code safely**: Execute untrusted or user‑provided code in a contained environment for AI agents or automation flows.
-- **Live product demos**: Ship a demo that runs the real backend logic in the browser without backend provisioning.
-- **Interactive docs and tutorials**: Let users run actual servers, seed data, and see real responses while following along.
-- **Collaborative tools**: Build multi‑user apps like whiteboards, editors, or chat that run locally and sync via portals.
-- **Browser‑based _server_ functions**: Run tasks that usually need cloud provisioning—like HTTP APIs, background jobs, or file processing entirely inside the user’s browser.
+### **Privacy-First Applications and Education**
-## Why pick the BrowserPod API?
+By keeping inputs and outputs on the user's device, BrowserPod enables privacy-conscious applications that bypass the jurisdictional risks of cloud data transfer. For educators, this model removes the operational burden of managing per-student sandboxes, making hands-on technical education economically feasible at any scale.
-- **Full-stack development**: BrowserPod runs full instances of backend frameworks enabling full-stack development without cloud provisioning.
-- **Real filesystem**: Create directories and files inside a virtual POSIX‑like tree.
-- **Portal URLs**: BrowserPod Portals allow to share working applications over a temporary, private and secure URL.
-- **Security**: The BrowserPod API boots instances in the browser's sandbox, inheriting its security.
-- **Cost**: Because BrowserPod runs instances in the browser, it comes at a fraction of the cost of cloud sandboxes, with a generous free tier.
+## How it works
-## How it works (high level)
+
-- BrowserPod ships a build of Node.js that targets CheerpOS (a runtime that provides a Linux‑like syscall interface to Wasm).
-- The browser’s JavaScript engine executes the Node runtime in the page.
-- Your project files live in a virtual filesystem inside the pod.
-- When your app listens on a port, BrowserPod can open a portal URL that forwards traffic into the pod.
+To understand how BrowserPod achieves high-fidelity behavior in a browser, it helps to look at the execution flow:
-See the [hosting guide](/docs/guides/hosting) for details on headers and setup.
+1. **Runtime Loading:** BrowserPod delivers complete runtime engines (starting with Node.js) compiled to WebAssembly. These engines target a Linux-compliant syscall interface rather than a limited JavaScript shim.
+2. **Execution:** The browser’s JavaScript engine executes the Wasm-compiled runtime using WebWorkers for true multi-threading and process isolation. This allows for complex, multi-process workloads that would normally require a full OS.
+3. **Resource Virtualization:** A block-based streaming virtual filesystem provides full POSIX compatibility. Disk images are streamed on-demand, and any file changes stay local to the browser session.
+4. **Networking via Portals:** When a service inside the pod listens on a port, BrowserPod automatically creates a **Portal**. This secure URL routes external traffic directly to the service running in the browser, enabling live previews and collaboration without any backend servers.
-## Supported runtimes
+## Roadmap
-BrowserPod currently supports Node.js runtime, support for Python and Ruby is coming soon.
+BrowserPod currently supports **Node.js**. Our goal is to expand this into a language-agnostic platform throughout 2026, with planned milestones across the year:
-## Community and support
+- Command-line tools (bash, git, coreutils), followed by **Python** and **Ruby** support.
+- Support for **Go** and **Rust** engines.
+- **Linux-class workloads** powered by CheerpX, enabling any unmodified Linux container to run in the browser.
+
+## Community and Support
-
----
diff --git a/sites/browserpod/src/content/docs/10-getting-started/01-quickstart.md b/sites/browserpod/src/content/docs/10-getting-started/01-quickstart.md
index 9e1a3149..06a8bb52 100644
--- a/sites/browserpod/src/content/docs/10-getting-started/01-quickstart.md
+++ b/sites/browserpod/src/content/docs/10-getting-started/01-quickstart.md
@@ -3,6 +3,8 @@ title: Quickstart
description: Getting started with BrowserPod
---
+BrowserPod provides a sandboxed runtime for executing code safely in the browser. This quickstart will get you running your first BrowserPod application in minutes.
+
## 1. Register a free account
In order to use BrowserPod, you need to obtain an API key.
diff --git a/sites/browserpod/src/content/docs/10-getting-started/02-expressjs.md b/sites/browserpod/src/content/docs/10-getting-started/02-expressjs.md
index 682bba78..9fdf8496 100644
--- a/sites/browserpod/src/content/docs/10-getting-started/02-expressjs.md
+++ b/sites/browserpod/src/content/docs/10-getting-started/02-expressjs.md
@@ -3,8 +3,7 @@ title: Set up a basic NPM-based project
description: In this tutorial you will set up a simple NPM project that runs an HTTP server using Express.js
---
-During this tutorial we will set up a basic project that uses BrowserPod to run
-a web server application entirely client side in the Browser.
+In this tutorial, we'll set up a basic project that uses BrowserPod to run a web server application entirely in the browser, with no backend infrastructure.
## 1. Get the code
diff --git a/sites/browserpod/src/content/docs/11-understanding-browserpod/04-syscalls.md b/sites/browserpod/src/content/docs/11-understanding-browserpod/04-syscalls.md
deleted file mode 100644
index 7e3197d8..00000000
--- a/sites/browserpod/src/content/docs/11-understanding-browserpod/04-syscalls.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: Syscalls
-description: What system calls are and how BrowserPod uses them
----
-
-BrowserPod runs Node.js inside the browser, so it cannot call your computer’s operating system directly. Instead, it uses a Linux-like syscall layer provided by **CheerpOS**.
-
-## What is a syscall?
-
-A **system call (syscall)** is how a program asks an operating system to do something privileged, like:
-
-- Open or write a file
-- Create a directory
-- Read the clock
-- Open a network socket
-
-In normal Node.js, these requests go to the host OS (macOS, Windows, Linux). In BrowserPod, they go to a **virtual syscall layer** implemented in the browser.
-
-## How syscalls work in BrowserPod
-
-1. Your code calls a built-in API (like `fs.readFile` or `http.createServer`).
-2. The runtime you've selected (e.g., Node, Python) translates that into syscalls (open, read, write, listen, etc.).
-3. CheerpOS intercepts those syscalls and fulfills them inside the browser using its virtual filesystem and networking layer.
-
-So the Node runtime _thinks_ it’s talking to Linux, but the work is actually done by the BrowserPod runtime in the browser.
-
-- **Most standard Node APIs work** because they map cleanly to the virtual syscall layer.
-- **Native binaries can fail** because they expect a real OS kernel, not a virtual one.
-- **File access is sandboxed** to the Pod’s virtual filesystem, not your computer’s disk.
diff --git a/sites/browserpod/src/content/docs/11-understanding-browserpod/06-portals.md b/sites/browserpod/src/content/docs/11-understanding-browserpod/06-portals.md
index ff19117f..fd6538b7 100644
--- a/sites/browserpod/src/content/docs/11-understanding-browserpod/06-portals.md
+++ b/sites/browserpod/src/content/docs/11-understanding-browserpod/06-portals.md
@@ -3,9 +3,19 @@ title: Portals
description: How Portals expose Pod servers to the outside world
---
-A **Portal** is BrowserPod’s way of exposing a server running inside a Pod to the outside world.
+A **Portal** is BrowserPod's controlled networking feature that exposes services running inside a Pod through secure, shareable URLs.
-When code inside the Pod starts listening on a port, BrowserPod creates a public URL that forwards traffic to that internal server.
+When code inside the Pod starts listening on a port, BrowserPod automatically creates a public URL that forwards traffic to that internal server. This unlocks powerful use cases that would traditionally require provisioning dedicated backend infrastructure for each session.
+
+## What Portals enable
+
+Portals unlock use cases that typically require backend infrastructure:
+
+- **Live previews**: Run a dev server in the browser and share the preview URL with teammates or stakeholders. Changes update in real-time without deploying to staging environments.
+- **Interactive demos**: Let users interact with working applications directly in documentation or product tours, without standing up demo infrastructure.
+- **Collaborative workflows**: Enable pair programming, troubleshooting sessions, or live code reviews by sharing a running environment via a simple URL.
+- **Shareable environments**: Create "click-to-open" demos where anyone with the link can access a fully functional application running in someone else's browser.
+- **Testing across devices**: Scan a QR code on your phone to test the server running on your laptop's browser, with changes reflected instantly.
## What a Portal is
diff --git a/sites/browserpod/src/content/docs/14-more/00-glossary.md b/sites/browserpod/src/content/docs/14-more/00-glossary.md
index ebc8520c..d2c370c0 100644
--- a/sites/browserpod/src/content/docs/14-more/00-glossary.md
+++ b/sites/browserpod/src/content/docs/14-more/00-glossary.md
@@ -9,7 +9,7 @@ The server-side part of a system that runs outside the browser.
## BrowserPod API
-The set of methods (like `pod.run` and file APIs) used to control the pod. New processes are started through the API, not by typing in the terminal.
+The JavaScript API for controlling a Pod. Provides methods for booting pods, running processes (`pod.run`), managing the virtual filesystem, and handling Portals. Used to execute code and manage the runtime environment entirely within the browser.
## CheerpOS
@@ -29,11 +29,11 @@ A filesystem created and managed in software rather than on the user’s real di
## Pod
-A running BrowserPod instance
+A running BrowserPod instance. Each Pod provides a sandboxed runtime environment with its own virtual filesystem, process space, and network layer. Pods run entirely in the browser and are ephemeral by design—they exist only while the browser tab is active.
## Portal
-A public URL that forwards external traffic to a port inside the pod.
+A secure, shareable URL that routes external traffic to a service listening on a port inside the Pod. Portals are created automatically when code binds to a port, enabling features like live previews, interactive demos, and collaborative workflows without requiring dedicated backend infrastructure.
## REPL
diff --git a/sites/browserpod/src/content/docs/14-more/01-FAQ.md b/sites/browserpod/src/content/docs/14-more/01-FAQ.md
index bfc92dd6..1432a83f 100644
--- a/sites/browserpod/src/content/docs/14-more/01-FAQ.md
+++ b/sites/browserpod/src/content/docs/14-more/01-FAQ.md
@@ -5,7 +5,7 @@ description: Common questions about BrowserPod
## What is BrowserPod?
-BrowserPod runs real Node.js applications inside the browser using WebAssembly. It provides a virtual filesystem and a portal system to expose local servers via public URLs.
+BrowserPod is a universal execution layer for browser-based compute. It provides a sandboxed runtime API for running code safely inside the browser using WebAssembly—whether that's for web-based IDEs, interactive documentation, untrusted code execution, or education. It includes a Linux-compliant environment with a virtual filesystem, process isolation, and Portals for controlled networking.
## Do I need a backend server?
@@ -26,3 +26,29 @@ Not directly. Use Wasm-compatible alternatives or `package.json` overrides when
## Which browsers are supported?
All the major browsers on desktop and mobile (Chrome, Edge, Firefox, Safari) are supported.
+
+## Why is BrowserPod good for running untrusted code?
+
+BrowserPod is designed for executing code in a sandboxed environment, whether that's user-provided scripts, AI-generated code, or dynamically loaded modules. It provides strong isolation through the browser's security sandbox, keeping execution local to the user's device while maintaining high fidelity with native environments.
+
+## How does BrowserPod compare to cloud sandboxes?
+
+BrowserPod runs on the user's device rather than provisioning cloud infrastructure for each session. This means:
+
+- **Lower cost**: No per-session VM costs. Computation uses underutilized client resources.
+- **Lower latency**: No cold starts or network round trips to remote servers.
+- **Better data locality**: User inputs and code execution stay in the browser by default, reducing your attack surface and compliance requirements.
+- **High fidelity**: BrowserPod provides a full Linux-compliant syscall interface with complete POSIX filesystem semantics, real process isolation, and true multi-threading. It runs complete, unmodified runtime engines (like the full Node.js) that behave identically to their native counterparts, rather than browser-specific reimplementations.
+- **Multi-language support**: Unlike solutions built for a single runtime, BrowserPod is designed from the ground up as a language-agnostic platform that can support Node.js, Python, Ruby, Go, Rust, and eventually full Linux containers.
+
+## Is my data secure in BrowserPod?
+
+Yes. BrowserPod runs entirely within the browser's security sandbox, which is battle-tested and continuously hardened by browser vendors. Code running in a Pod cannot access the user's operating system, local files (unless explicitly provided), or other browser tabs. Data stays on the user's device by default unless your application specifically transmits it elsewhere.
+
+## What is the performance like?
+
+BrowserPod uses WebAssembly to run runtime engines at near-native speed. It supports real multi-process workloads with true concurrency via WebWorkers. Performance is suitable for computationally heavy tasks, including development tools, build pipelines, package managers, and code execution workflows.
+
+## What are Portals?
+
+Portals are BrowserPod's controlled networking feature. When code inside a Pod listens on a port, BrowserPod automatically creates a secure, shareable URL that routes traffic to that service. This enables live previews, interactive demos, and collaborative workflows without provisioning dedicated backend infrastructure.