initial tweaking (needs extra review)

- removed syscalls page

Author: codingfrog27

sites/browserpod/src/content/docs/00-overview.mdx

@@ -1,7 +1,7 @@
 ---
 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";
@@ -29,8 +29,8 @@ import { DISCORD_URL } from "@/consts.ts";
 	</a>
 </div>
 
-**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, providing a sandboxed runtime API for running full-stack workloads directly inside the browser.
+Instead of provisioning a cloud server, BrowserPod's API enables a client browser to host full runtimes compiled to WebAssembly (Wasm), running at near native speed.
 
 <div class="m-4 flex justify-center">
 	[Get started](/docs/getting-started/quickstart) · [Basic
@@ -43,40 +43,42 @@ BrowserPod is ephemeral by design. Each **pod** (_see [pod](/docs/more/glossary#
 
 At a high level, BrowserPod gives you:
 
-- 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
+- A **sandboxed runtime** for executing untrusted code in the browser (starting with Node.js, with Python, Ruby, Go, and Rust coming soon)
+- A block-based streaming virtual filesystem with familiar file and directory behavior
+- **Process isolation** and true concurrency via WebWorkers
+- **Portals** for controlled networking that expose services at shareable URLs
 
-Everything runs client‑side within the browser sandbox, so users don’t need to install anything.
+Everything runs client‑side within the browser sandbox, with no backend infrastructure required.
 
 ## What you can do with BrowserPod
 
-- **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.
+- **Execute AI-generated code safely**: Run code produced by AI agents or models in a contained environment next to the user, with fast startup, strong isolation, and better performance than cloud-based sandboxes. Reduce per-session costs while tightening security boundaries.
+- **Build web-based IDEs and development environments**: Power real development workflows in the browser with package installs, dev servers, build tools, and previews—all with high fidelity to native environments.
+- **Create interactive documentation and live demos**: Turn documentation into runnable environments where users can modify, execute, and share examples without leaving the page or provisioning infrastructure.
+- **Enable education at scale**: Provide high-fidelity learning environments with minimal operational overhead. Eliminate per-student sandbox costs to make hands-on education economically feasible at scale.
+- **Process sensitive data locally**: Keep user inputs and outputs in the browser by default, enabling privacy-first applications and removing jurisdictional risks associated with cloud data transfer.
 
 ## Why pick the BrowserPod API?
 
-- **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.
+- **Economics**: BrowserPod runs on the user's device, eliminating per-session cloud infrastructure costs. This fundamental shift makes previously expensive use cases—like AI code execution, interactive demos, and education at scale—economically viable.
+- **Latency**: No cold starts, no network round trips to remote sandboxes. Code executes immediately in the browser where the user already is.
+- **Security & data locality**: BrowserPod inherits the browser's battle-tested security model. User data and code execution stay local by default, reducing your attack surface and compliance burden.
+- **High fidelity**: Full Linux-compliant environment with POSIX filesystem, process isolation, and real concurrency—not a limited simulation. Run actual frameworks and tools without modification.
+- **Portals**: Share working applications instantly via secure, temporary URLs. Enable live previews, collaborative troubleshooting, and interactive demos without standing up dedicated infrastructure.
 
 ## 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.
+- BrowserPod provides complete runtime engines (starting with Node.js) compiled to WebAssembly, targeting a Linux-compliant syscall interface.
+- The browser's JavaScript engine executes the runtime with near-native performance, supporting real multi-process workloads.
+- A virtual filesystem provides full POSIX compatibility, with on-demand streaming of disk images. Changes stay local and can persist across sessions.
+- When your code listens on a port, BrowserPod automatically creates a Portal—a secure URL that routes external traffic to the service running inside the browser.
+- All execution happens within the browser's security sandbox, isolated from the user's operating system.
 
 See the [hosting guide](/docs/guides/hosting) for details on headers and setup.
 
 ## Supported runtimes
 
-BrowserPod currently supports Node.js runtime, support for Python and Ruby is coming soon.
+BrowserPod currently supports Node.js. Python, Ruby, Go, and Rust support will be released throughout 2026. By the end of 2026, BrowserPod will support Linux-class workloads, enabling any Linux container to run in the browser.
 
 ## Community and support
 

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.

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
 

sites/browserpod/src/content/docs/11-understanding-browserpod/04-syscalls.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
 

sites/browserpod/src/content/docs/11-understanding-browserpod/06-portals.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
 

sites/browserpod/src/content/docs/14-more/00-glossary.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 untrusted code—including AI-generated code, user scripts, or agent-assembled programs—safely inside the browser using WebAssembly. 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,28 @@ 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.
+
+## Is BrowserPod good for AI-generated code?
+
+Yes. BrowserPod is specifically designed for executing untrusted code, including code generated by AI models or agents. 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**: Full Linux-compliant environment, not a limited simulation.
+
+## 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, and AI code execution.
+
+## 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.