feat(website): add FAQ section and sync README with landing page

Author: NathanFlurry

CLAUDE.md

@@ -75,6 +75,13 @@ Follow the style in `packages/secure-exec/src/index.ts`.
 - comment tricky ordering/invariants; skip noise
 - add inline comments and doc comments when behavior is non-obvious, especially where runtime/bridge/driver pieces depend on each other
 
+## Landing Page & README Sync
+
+- `README.md` mirrors the landing page (`packages/website/src/pages/index.astro` and its components) 1:1 in content and structure
+- when updating the landing page (hero copy, features, benchmarks, comparison, FAQ, or CTA), update `README.md` to match
+- when updating `README.md`, update the landing page to match
+- the landing page section order is: Hero → Code Example → Why Secure Exec (features) → Benchmarks → Secure Exec vs. Sandboxes → FAQ → CTA → Footer
+
 ## Documentation
 
 - docs pages that must stay current with API changes:

README.md

@@ -1,24 +1,194 @@
-# Secure Exec SDK
+# Secure Exec
 
-Run sandboxed Node.js code using a driver-based runtime.
+**Secure Node.js Execution Without a Sandbox**
 
-## Features
+A lightweight library for secure Node.js execution. No containers, no VMs — just npm-compatible sandboxing out of the box. Powered by the same tech as Cloudflare Workers.
 
-- **Minimal overhead**: TODO
-- **Just a library**: TODO
-- **Low memory overhead**: TODO
+```
+npm install secure-exec
+```
 
-TODO:
+## Give your AI agent secure code execution
 
-- **Node runtime**: isolated-vm backed sandbox execution with driver-owned capability wiring.
-- **Browser runtime**: Worker-backed execution through `NodeRuntime` + browser driver factories.
-- **Driver-based**: Provide a driver to map filesystem, network, and child_process.
-- **Permissions**: Gate syscalls with custom allow/deny functions.
-- **Opt-in system features**: Disable network/child_process/FS by omission.
+Expose secure-exec as a tool with the Vercel AI SDK. Your agent can execute arbitrary code without risking your infrastructure.
 
-## Examples
+```typescript
+import { generateText, tool } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { NodeRuntime, createNodeDriver, createNodeRuntimeDriverFactory } from "secure-exec";
+import { z } from "zod";
 
-- Browser playground: `pnpm -C packages/playground dev`
+const runtime = new NodeRuntime({
+  systemDriver: createNodeDriver({ permissions: { fs: true, network: true } }),
+  runtimeDriverFactory: createNodeRuntimeDriverFactory(),
+  memoryLimit: 64,
+  cpuTimeLimitMs: 5000,
+});
+
+const result = await generateText({
+  model: anthropic("claude-sonnet-4-20250514"),
+  tools: {
+    execute: tool({
+      description: "Run JavaScript in a secure sandbox",
+      parameters: z.object({ code: z.string() }),
+      execute: async ({ code }) => {
+        const logs: string[] = [];
+        const res = await runtime.exec(code, {
+          onStdio: (e) => logs.push(e.message),
+        });
+        return { exitCode: res.code, output: logs.join("\n") };
+      },
+    }),
+  },
+  prompt: "Calculate the first 20 fibonacci numbers",
+});
+```
+
+## Why Secure Exec
+
+Give your AI agent the ability to write and run code safely.
+
+- **No infrastructure required** — No Docker daemon, no hypervisor, no orchestrator. Runs anywhere Node.js, Bun, or an HTML5 browser runs. Deploy to Lambda, a VPS, or a static site — your existing deployment works.
+- **Node.js & npm compatibility** — fs, child_process, http, dns, process, os — bridged to real host capabilities, not stubbed. Run Express, Hono, Next.js, and any npm package. [Compatibility matrix →](https://secure-exec.dev/docs/node-compatability)
+- **Built for AI agents** — Give your AI agent the ability to write and run code safely. Works with the Vercel AI SDK, LangChain, and any tool-use framework.
+- **Deny-by-default permissions** — Filesystem, network, child processes, and env vars are all blocked unless explicitly allowed. Permissions are composable functions — grant read but not write, allow fetch but block spawn.
+- **Configurable resource limits** — CPU time budgets and memory caps. Runaway code is terminated deterministically with exit code 124 — no OOM crashes, no infinite loops, no host exhaustion.
+- **Powered by V8 isolates** — The same isolation primitive behind Cloudflare Workers for Platforms and every browser tab. Battle-tested at scale by the infrastructure you already trust.
+
+## Benchmarks
+
+V8 isolates vs. sandboxes.
+
+### Cold start
+
+| Percentile | Secure Exec | Fastest sandbox |
+|------------|-------------|-----------------|
+| p50        | 16.2 ms     | 440 ms          |
+| p95        | 17.9 ms     | 950 ms          |
+| p99        | 17.9 ms     | 3,150 ms        |
+
+**What's measured:** Time from requesting an execution to first code running. Secure Exec spins up a V8 isolate inside the host process — no container, no VM, no network hop. Sandbox baseline: [e2b](https://www.computesdk.com/benchmarks/), the fastest provider on ComputeSDK as of March 18, 2026. Secure Exec numbers: median of 10,000 runs (100 iterations × 100 samples) on Intel i7-12700KF.
+
+### Memory per instance
+
+| Runtime                  | Memory    |
+|--------------------------|-----------|
+| Secure Exec              | ~3.4 MB   |
+| Sandbox provider minimum | ~256 MB   |
+
+**75x smaller.** V8 isolates share the host process and its V8 engine. Each additional execution only adds its own heap and stack. On a 1 GB server, you can run ~210 concurrent Secure Exec executions vs. ~4 sandboxes.
+
+### Cost per execution-second
+
+| Hardware     | Secure Exec      | vs. cheapest sandbox ($0.000625/s) |
+|--------------|------------------|------------------------------------|
+| AWS ARM      | $0.000011/s      | 56x cheaper                        |
+| AWS x86      | $0.000014/s      | 45x cheaper                        |
+| Hetzner ARM  | $0.0000016/s     | 380x cheaper                       |
+| Hetzner x86  | $0.0000027/s     | 232x cheaper                       |
+
+Each execution uses ~3.4 MB instead of a 256 MB container minimum, and you run on your own hardware. Sandbox baseline: Cloudflare Containers, billed at $0.0000025/GiB·s with 256 MB minimum.
+
+## Secure Exec vs. Sandboxes
+
+Same isolation guarantees, without the infrastructure overhead.
+
+**Secure Exec:**
+- ✓ Native V8 performance
+- ✓ Granular deny-by-default permissions
+- ✓ Just npm install — no vendor account
+- ✓ No API keys to manage
+- ✓ Run on any cloud or hardware
+- ✓ No egress fees
+
+**Sandbox:**
+- ✓ Native container performance
+- ✗ Coarse-grained permissions
+- ✗ Vendor account required
+- ✗ API keys to manage
+- ✗ Hardware lock-in
+- ✗ Per-GB egress fees
+
+[Full comparison →](https://secure-exec.dev/docs/sandbox-vs-secure-exec)
+
+## FAQ
+
+<details>
+<summary>How does it work?</summary>
+
+Secure Exec runs untrusted code inside [V8 isolates](https://v8.dev/docs/embed) — the same isolation primitive that powers every Chromium tab and Cloudflare Workers. Each execution gets its own heap, its own globals, and a deny-by-default permission boundary. There is no container, no VM, and no Docker daemon — just fast, lightweight isolation using battle-tested web technology. [Architecture →](https://secure-exec.dev/docs/sdk-overview)
+</details>
+
+<details>
+<summary>Does this require Docker, nested virtualization, or a hypervisor?</summary>
+
+No. Secure Exec is a pure npm package — `npm install secure-exec` is all you need. It has zero infrastructure dependencies: no Docker daemon, no hypervisor, no orchestrator, no sidecar. It runs anywhere Node.js or Bun runs.
+</details>
+
+<details>
+<summary>Can it run in serverless environments?</summary>
+
+We are actively validating serverless platforms, but Secure Exec should work everywhere that provides a standard Node.js-like runtime. This includes Vercel Fluid Compute, AWS Lambda, and Google Cloud Run. Cloudflare Workers is not supported because it does not expose the V8 APIs that Secure Exec relies on.
+</details>
+
+<details>
+<summary>When should I use a sandbox vs. Secure Exec?</summary>
+
+Use **Secure Exec** when you need fast, lightweight code execution — AI tool calls, code evaluation, user-submitted scripts — without provisioning infrastructure. Use a **sandbox** (e2b, Modal, Daytona) when you need a full operating-system environment with persistent disk, root access, or GPU passthrough. [Full comparison →](https://secure-exec.dev/docs/sandbox-vs-secure-exec)
+</details>
+
+<details>
+<summary>Can I run npm install in Secure Exec to dynamically install modules?</summary>
+
+Yes. Secure Exec supports dynamic module installation via npm inside the execution environment.
+</details>
+
+<details>
+<summary>Can I use it to run dev servers like Express, Hono, or Next.js?</summary>
+
+Yes. Secure Exec bridges Node.js APIs including http, net, and child_process, so frameworks like Express, Hono, and Next.js work out of the box.
+</details>
+
+<details>
+<summary>Can it be used for long-running tasks?</summary>
+
+Yes. For orchestrating stateful, long-running processes efficiently, we recommend pairing Secure Exec with [Rivet Actors](https://rivet.dev/docs/actors).
+</details>
+
+<details>
+<summary>What are common use cases?</summary>
+
+- AI agent code evaluation and tool use
+- User-facing dev servers (Express, Hono, Next.js)
+- MCP tool-code execution
+- Sandboxed plugin / extension systems
+- Interactive coding playgrounds
+</details>
+
+<details>
+<summary>Does this have Node.js compatibility?</summary>
+
+Yes. Most Node.js core modules work — including fs, child_process, http, dns, process, and os. These are bridged to real host capabilities, not stubbed. [Compatibility matrix →](https://secure-exec.dev/docs/node-compatability)
+</details>
+
+<details>
+<summary>Does this have access to a full operating system?</summary>
+
+Yes. Secure Exec includes a virtual kernel with a system bridge that supports a granular permission model. Filesystem, network, child processes, and environment variables are all available — gated behind deny-by-default permissions.
+</details>
+
+<details>
+<summary>How does Secure Exec compare to WASM-based JavaScript runtimes like QuickJS?</summary>
+
+WASM-based runtimes like [QuickJS](https://bellard.org/quickjs/) (via quickjs-emscripten) compile a separate JS engine to WebAssembly, which means your code runs through an interpreter inside WASM — not native V8. Secure Exec uses native V8 isolates directly, so you get the same JIT-compiled performance as JavaScript running on the host. No interpretation overhead, no WASM translation layer, and full Node.js API compatibility.
+</details>
+
+## Links
+
+- [Documentation](https://secure-exec.dev/docs)
+- [Changelog](https://github.com/rivet-dev/secure-exec/releases)
+- [Discord](https://rivet.dev/discord)
+- [GitHub](https://github.com/rivet-dev/secure-exec)
 
 ## License
 

docs/cost-evaluation.mdx

@@ -5,6 +5,15 @@ description: "Cost-per-second comparison of Secure Exec on self-hosted hardware
 
 {/* Figures generated by scripts/calculate-costs.js — rerun when updating pricing */}
 
+## Why it's cheaper
+
+Secure Exec costs less per execution for two reasons:
+
+- **Uses far less memory per execution.** Each V8 isolate adds ~3.4 MB to the host process. Sandbox providers allocate a full container with a minimum of 256 MB, even if the code inside uses a fraction of that. This means you fit ~75× more concurrent executions on the same hardware.
+- **Runs on your own hardware.** You choose your cloud, instance type, and region. Self-hosted servers (AWS, Hetzner, etc.) are significantly cheaper per compute-second than per-container sandbox billing, and you avoid egress fees and vendor lock-in.
+
+All Secure Exec figures assume 70% utilization (30% idle capacity headroom) to account for real-world bin-packing inefficiency. Even with this conservative assumption, the cost advantage is substantial.
+
 ## Methodology
 
 We compare the **cost per execution-second**: the cost of running one isolated execution for one second.

packages/website/src/components/Benchmarks.tsx

@@ -16,7 +16,7 @@ function InfoTooltip({ children }: { children: React.ReactNode }) {
       >
         <path d="M8 0a8 8 0 100 16A8 8 0 008 0zm1 12H7V7h2v5zm-1-6a1 1 0 110-2 1 1 0 010 2z" />
       </svg>
-      <span className="absolute bottom-full left-0 mb-2 w-72 p-3 rounded-lg bg-zinc-800/95 backdrop-blur-sm text-[11px] text-zinc-300 leading-relaxed shadow-xl border border-zinc-700/50 z-50 opacity-0 pointer-events-none group-hover/tip:opacity-100 group-hover/tip:pointer-events-auto transition-opacity duration-200 [&_a]:text-white [&_a]:underline [&_a]:underline-offset-2">
+      <span className="absolute bottom-full left-0 mb-2 w-80 p-3 rounded-lg bg-zinc-800/95 backdrop-blur-sm text-[11px] text-zinc-300 leading-relaxed shadow-xl border border-zinc-700/50 z-50 opacity-0 pointer-events-none group-hover/tip:opacity-100 group-hover/tip:pointer-events-auto transition-opacity duration-200 [&_a]:text-white [&_a]:underline [&_a]:underline-offset-2 [&_strong]:text-zinc-200 [&_strong]:font-medium">
         {children}
       </span>
     </span>
@@ -41,12 +41,17 @@ function ColdStartChart() {
           <h4 className="text-sm font-medium text-white flex items-center">
             Cold start
             <InfoTooltip>
-            Time to interactive (TTI). Sandbox values use the fastest provider — e2b (best median) from{" "}
-            <a href="https://www.computesdk.com/benchmarks/" target="_blank" rel="noopener noreferrer">
-              ComputeSDK
-            </a>{" "}
-            as of March 2026. Secure Exec measured over 100 iterations × 100 samples.{" "}
-            <a href="/docs/benchmarks">Our benchmarks →</a>
+              <strong>What's measured:</strong> Time from requesting an execution to first code running.
+              <br /><br />
+              <strong>Why the gap:</strong> Secure Exec spins up a V8 isolate inside the host process. No container, no VM, no network hop. Sandboxes must boot an entire container or microVM, allocate memory, and establish a network connection before code can run.
+              <br /><br />
+              <strong>Sandbox baseline:</strong> e2b, the fastest provider on{" "}
+              <a href="https://www.computesdk.com/benchmarks/" target="_blank" rel="noopener noreferrer">ComputeSDK</a>
+              {" "}as of March 18, 2026.
+              <br /><br />
+              <strong>Secure Exec:</strong> Median of 10,000 runs (100 iterations × 100 samples) on Intel i7-12700KF.
+              <br /><br />
+              <a href="/docs/benchmarks">Our benchmarks →</a>
             </InfoTooltip>
           </h4>
           <p className="text-[11px] text-zinc-600 italic mt-1">Lower is better</p>
@@ -202,8 +207,14 @@ function CostChart() {
           <h4 className="text-sm font-medium text-white flex items-center">
             Cost per execution-second
             <InfoTooltip>
-              Sandbox value uses the cheapest provider — Cloudflare Containers (256 MB min, billed per second at $0.0000025/GiB·s) as of March 2026.
-              Secure Exec: 3.4 MB baseline (p95) with 30% empty capacity assumed across self-hosted hardware tiers.{" "}
+              <strong>What's measured:</strong> <code className="text-[10px] bg-white/10 px-1 py-0.5 rounded">server price per second ÷ concurrent executions per server</code>
+              <br /><br />
+              <strong>Why it's cheaper:</strong> Each execution uses ~3.4 MB instead of a 256 MB container minimum. And you run on your own hardware, which is significantly cheaper than per-second sandbox billing.
+              <br /><br />
+              <strong>Sandbox baseline:</strong> Cloudflare Containers, the cheapest sandbox provider benchmarked. Billed at $0.0000025/GiB·s with a 256 MB minimum (March 18, 2026).
+              <br /><br />
+              <strong>Secure Exec:</strong> 3.4 MB baseline per execution, assuming 70% utilization. Select a hardware tier above to compare.
+              <br /><br />
               <a href="/docs/benchmarks">Our benchmarks →</a>
               {" · "}
               <a href="/docs/cost-evaluation">Full cost breakdown →</a>
@@ -294,7 +305,7 @@ export function Benchmarks() {
             transition={{ duration: 0.5, delay: 0.1 }}
             className="max-w-xl text-base leading-relaxed text-zinc-500"
           >
-            V8 isolates vs. container-based sandboxes.
+            V8 isolates vs. sandboxes.
           </motion.p>
         </div>
 
@@ -316,8 +327,16 @@ export function Benchmarks() {
             label="Memory per instance"
             tooltip={
               <>
-                Secure Exec memory is the converged at-scale average per execution.
-                Sandbox value uses the smallest minimum among popular providers (e2b, Daytona, Modal, Cloudflare) as of March 2026 — 256 MB for Modal and Cloudflare.{" "}
+                <strong>What's measured:</strong> Memory footprint added per concurrent execution.
+                <br /><br />
+                <strong>Why the gap:</strong> V8 isolates share the host process and its V8 engine. Each additional execution only adds its own heap and stack (~3.4 MB). Sandboxes allocate a dedicated container with a minimum memory reservation, even if the code inside uses far less.
+                <br /><br />
+                <strong>What this means:</strong> On a 1 GB server, you can run ~210 concurrent Secure Exec executions vs. ~4 sandboxes.
+                <br /><br />
+                <strong>Sandbox baseline:</strong> 256 MB, the smallest minimum among popular providers (Modal, Cloudflare Containers) as of March 18, 2026.
+                <br /><br />
+                <strong>Secure Exec:</strong> 3.4 MB, the converged average per execution under sustained load.
+                <br /><br />
                 <a href="/docs/benchmarks">Our benchmarks →</a>
               </>
             }
@@ -332,23 +351,6 @@ export function Benchmarks() {
           <CostChart />
         </motion.div>
 
-        <motion.p
-          initial={{ opacity: 0 }}
-          whileInView={{ opacity: 1 }}
-          viewport={{ once: true }}
-          transition={{ duration: 0.5, delay: 0.3 }}
-          className="mt-4 text-xs text-zinc-600"
-        >
-          Sandbox provider numbers based on published documentation and benchmarks.
-          Secure Exec measured on Intel i7-12700KF, Node.js v24.{" "}
-          <a href="/docs/benchmarks" className="underline underline-offset-2 hover:text-zinc-500">
-            Methodology →
-          </a>
-          {" · "}
-          <a href="/docs/cost-evaluation" className="underline underline-offset-2 hover:text-zinc-500">
-            Cost breakdown →
-          </a>
-        </motion.p>
       </div>
     </section>
   );