chore: docs

Author: NathanFlurry

README.md

@@ -141,18 +141,25 @@ V8 isolates vs. sandboxes.
 
 ## Secure Exec vs. Sandboxes
 
-Same isolation guarantees, without the infrastructure overhead.
+Not every workload needs a full OS. Secure Exec gives you V8-level isolation for code execution — no container required.
+
+- **Secure Exec** — Run untrusted code (Node.js, Python) inside your backend process
+- **Sandboxes** — Spin up a full OS with root access, system packages, and persistent disk
 
 |                      | Secure Exec                              | Sandbox                      |
 |----------------------|------------------------------------------|------------------------------|
 | **Performance**      | ✅ Native V8                             | ✅ Native container          |
 | **Permissions**      | ✅ Granular deny-by-default              | ❌ Coarse-grained            |
 | **Setup**            | ✅ Just `npm install` — no vendor account | ❌ Vendor account required  |
-| **API keys**         | ✅ None                                  | ❌ Required                  |
 | **Infrastructure**   | ✅ Run on any cloud or hardware          | ❌ Hardware lock-in          |
 | **Egress**           | ✅ No egress fees                        | ❌ Per-GB egress fees        |
+| **API keys**         | ✅ None                                  | ❌ Required                  |
+
+[**Full comparison guide →**](https://secureexec.dev/docs/comparison/sandbox)
 
-[Full comparison →](https://secureexec.dev/docs/comparison/sandbox)
+> **Need a full sandboxed operating system? We've got that too.** <br/>
+>
+> The [Sandbox Agent SDK](https://sandboxagent.dev/) lets you run coding agents in sandboxes and control them over HTTP. Supports Claude Code, Codex, OpenCode, Amp, and Pi. Works with E2B, Daytona, Vercel, Docker, and Cloudflare.
 
 ## FAQ
 
@@ -189,22 +196,22 @@ Yes. Secure Exec supports dynamic module installation via npm inside the executi
 <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.
+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. For production deployments, pair Secure Exec with [Rivet Actors](https://rivet.dev/docs/actors) to get built-in routing, scaling, and lifecycle management for each server instance.
 </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).
+Yes. For orchestrating stateful, long-running tasks, we recommend pairing Secure Exec with [Rivet Actors](https://rivet.dev/docs/actors). Rivet Actors provide durable state, automatic persistence, and fault-tolerant orchestration — so each long-running task survives restarts and can be monitored, paused, or resumed without you building that infrastructure yourself.
 </details>
 
 <details>
 <summary>What are common use cases?</summary>
 
-- AI agent code evaluation and tool use
-- User-facing dev servers (Express, Hono, Next.js)
+- [AI agent code evaluation and tool use](https://secureexec.dev/docs/use-cases/ai-agent-code-eval)
+- [User-facing dev servers (Express, Hono, Next.js)](https://secureexec.dev/docs/use-cases/dev-servers)
 - MCP tool-code execution
-- Sandboxed plugin / extension systems
+- [Sandboxed plugin / extension systems](https://secureexec.dev/docs/use-cases/plugin-systems)
 - Interactive coding playgrounds
 </details>
 
@@ -220,6 +227,12 @@ Yes. Most Node.js core modules work — including fs, child_process, http, dns,
 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>Does Secure Exec support JIT compilation?</summary>
+
+Yes. Secure Exec runs on native V8 isolates, so your code is JIT-compiled by V8's TurboFan optimizing compiler — the same pipeline that powers Chrome and Node.js. This means full optimization tiers, inline caching, and speculative optimization out of the box.
+</details>
+
 <details>
 <summary>How does Secure Exec compare to WASM-based JavaScript runtimes like QuickJS?</summary>
 

docs/api-reference.mdx

@@ -5,24 +5,18 @@ description: Complete reference for all secure-exec exports.
 
 ## Package Structure
 
-secure-exec is split into focused packages. The umbrella `secure-exec` package re-exports everything for convenience.
-
 | Package | Contents |
 |---|---|
-| `@secure-exec/core` | Shared types, utilities, bridge guest code, `NodeRuntime`, `PythonRuntime` classes |
-| `@secure-exec/node` | Node.js V8 isolate runtime driver, `createNodeDriver`, `createNodeRuntimeDriverFactory` |
-| `@secure-exec/browser` | Browser Web Worker runtime driver, `createBrowserDriver`, `createBrowserRuntimeDriverFactory` |
-| `@secure-exec/python` | Pyodide runtime driver, `createPyodideRuntimeDriverFactory` |
+| `secure-exec` | Main package — `NodeRuntime`, system drivers, execution environment factories, filesystem, network, and permissions |
 | `@secure-exec/typescript` | Sandboxed TypeScript compiler tools |
-| `secure-exec` | Umbrella barrel — re-exports all of the above |
 
 ---
 
 ## Runtimes
 
 ### `NodeRuntime`
 
-<sub>Package: `@secure-exec/core` (also re-exported from `secure-exec`)</sub>
+<sub>Exported from `secure-exec`</sub>
 
 Sandboxed JavaScript runtime using a V8 isolate.
 
@@ -85,41 +79,11 @@ createTypeScriptTools(options: TypeScriptToolsOptions)
 
 ---
 
-### `PythonRuntime`
-
-<sub>Package: `@secure-exec/core` (also re-exported from `secure-exec`)</sub>
-
-Sandboxed Python runtime using Pyodide in a Worker thread.
-
-```ts
-new PythonRuntime(options: PythonRuntimeOptions)
-```
-
-**`PythonRuntimeOptions`**
-
-| Option | Type | Description |
-|---|---|---|
-| `systemDriver` | `SystemDriver` | Host capabilities. **Required.** |
-| `runtimeDriverFactory` | `PythonRuntimeDriverFactory` | Creates the Pyodide worker. **Required.** |
-| `cpuTimeLimitMs` | `number` | CPU time budget in ms. |
-| `onStdio` | `StdioHook` | Default console output hook. |
-
-**Methods**
-
-| Method | Returns | Description |
-|---|---|---|
-| `exec(code, options?)` | `Promise<ExecResult>` | Execute Python code without a return value. |
-| `run<T>(code, options?)` | `Promise<PythonRunResult<T>>` | Execute Python code and return a value. |
-| `dispose()` | `void` | Release resources synchronously. |
-| `terminate()` | `Promise<void>` | Terminate the runtime. |
-
----
-
 ## System Driver Factories
 
 ### `createNodeDriver(options?)`
 
-<sub>Package: `@secure-exec/node` (also re-exported from `secure-exec`)</sub>
+<sub>Exported from `secure-exec`</sub>
 
 Creates a system driver for Node.js environments.
 
@@ -142,7 +106,7 @@ createNodeDriver(options?: NodeDriverOptions): SystemDriver
 
 ### `createBrowserDriver(options?)`
 
-<sub>Package: `@secure-exec/browser` (also re-exported from `secure-exec`)</sub>
+<sub>Exported from `secure-exec`</sub>
 
 Creates a system driver for browser environments. Returns a promise because OPFS initialization is async.
 
@@ -160,13 +124,13 @@ createBrowserDriver(options?: BrowserDriverOptions): Promise<SystemDriver>
 
 ---
 
-## Runtime Driver Factories
+## Execution Environment Setup
 
 ### `createNodeRuntimeDriverFactory(options?)`
 
-<sub>Package: `@secure-exec/node` (also re-exported from `secure-exec`)</sub>
+<sub>Re-exported from `secure-exec`</sub>
 
-Creates a factory for Node.js V8 isolate runtime drivers.
+Creates the execution environment factory for Node.js V8 isolates. Pass the result as the `runtimeDriverFactory` option when constructing a `NodeRuntime`.
 
 ```ts
 createNodeRuntimeDriverFactory(options?: {
@@ -176,33 +140,23 @@ createNodeRuntimeDriverFactory(options?: {
 
 ### `createBrowserRuntimeDriverFactory(options?)`
 
-<sub>Package: `@secure-exec/browser` (also re-exported from `secure-exec`)</sub>
+<sub>Re-exported from `secure-exec`</sub>
 
-Creates a factory for browser Worker-based runtime drivers.
+Creates the execution environment factory for browser Worker-based sandboxes. Pass the result as the `runtimeDriverFactory` option when constructing a `NodeRuntime`.
 
 ```ts
 createBrowserRuntimeDriverFactory(options?: {
   workerUrl?: URL | string;
 }): NodeRuntimeDriverFactory
 ```
 
-### `createPyodideRuntimeDriverFactory()`
-
-<sub>Package: `@secure-exec/python` (also re-exported from `secure-exec`)</sub>
-
-Creates a factory for Pyodide-based Python runtime drivers.
-
-```ts
-createPyodideRuntimeDriverFactory(): PythonRuntimeDriverFactory
-```
-
 ---
 
 ## Filesystem
 
 ### `createInMemoryFileSystem()`
 
-<sub>Package: `@secure-exec/core` (also re-exported from `secure-exec`)</sub>
+<sub>Exported from `secure-exec`</sub>
 
 Creates a fully in-memory filesystem backed by Maps.
 
@@ -212,7 +166,7 @@ createInMemoryFileSystem(): InMemoryFileSystem
 
 ### `createOpfsFileSystem()`
 
-<sub>Package: `@secure-exec/browser` (also re-exported from `secure-exec`)</sub>
+<sub>Exported from `secure-exec`</sub>
 
 Creates an OPFS-backed filesystem (browser only).
 
@@ -251,7 +205,7 @@ new NodeFileSystem()
 
 ### `createDefaultNetworkAdapter()`
 
-<sub>Package: `@secure-exec/node` (also re-exported from `secure-exec`)</sub>
+<sub>Exported from `secure-exec`</sub>
 
 Creates a network adapter with real fetch, DNS, and HTTP support (Node.js only).
 
@@ -261,7 +215,7 @@ createDefaultNetworkAdapter(): NetworkAdapter
 
 ### `createBrowserNetworkAdapter()`
 
-<sub>Package: `@secure-exec/browser` (also re-exported from `secure-exec`)</sub>
+<sub>Exported from `secure-exec`</sub>
 
 Creates a fetch-only network adapter for browser environments. No DNS support.
 
@@ -283,7 +237,7 @@ createBrowserNetworkAdapter(): NetworkAdapter
 
 ## Permissions
 
-<sub>Package: `@secure-exec/core` (also re-exported from `secure-exec`)</sub>
+<sub>Exported from `secure-exec`</sub>
 
 ### Pre-built helpers
 
@@ -336,20 +290,6 @@ Each field accepts a `PermissionCheck`, which is either a boolean or a function
 { code: number; errorMessage?: string; exports?: T }
 ```
 
-### `PythonRunResult<T>`
-
-```ts
-{ code: number; errorMessage?: string; value?: T; globals?: Record<string, unknown> }
-```
-
-### `PythonRunOptions`
-
-Extends `ExecOptions` with:
-
-| Option | Type | Description |
-|---|---|---|
-| `globals` | `string[]` | Python globals to return. |
-
 ### `StdioHook`
 
 ```ts

docs/architecture.mdx

@@ -10,7 +10,7 @@ Every secure-exec sandbox has three layers: a **runtime** (public API), a **brid
 ```mermaid
 flowchart TB
     subgraph Host["Host Process"]
-        RT["Runtime<br/>(NodeRuntime / PythonRuntime)"]
+        RT["Runtime<br/>(NodeRuntime)"]
         SD["System Driver<br/>(filesystem, network, processes, permissions)"]
     end
     subgraph Isolate["Sandbox"]
@@ -29,12 +29,13 @@ User code runs inside the sandbox and can only reach host capabilities through t
 
 ### Runtime
 
-The public API. `NodeRuntime` and `PythonRuntime` are thin facades that accept a system driver and a runtime driver factory, then delegate all execution to the runtime driver.
+The public API. `NodeRuntime` is a thin facade that accepts a system driver, then delegates all execution to the isolate.
 
 ```ts
+import { NodeRuntime, createNodeDriver } from "secure-exec";
+
 const runtime = new NodeRuntime({
   systemDriver: createNodeDriver(),
-  runtimeDriverFactory: createNodeRuntimeDriverFactory(),
 });
 
 await runtime.exec("console.log('hello')");
@@ -59,10 +60,6 @@ Each capability is wrapped in a permission layer before the bridge can call it.
 
 The narrow interface between the sandbox and the host. All privileged operations pass through the bridge. It serializes requests, enforces payload size limits, and routes calls to the appropriate system driver capability.
 
-### Runtime Driver
-
-Manages the actual execution environment. This is where the runtime-specific isolation mechanism lives.
-
 ## Node Runtime
 
 On Node, the sandbox is a V8 isolate managed by `isolated-vm`.
@@ -71,7 +68,6 @@ On Node, the sandbox is a V8 isolate managed by `isolated-vm`.
 flowchart TB
     subgraph Host["Host (Node.js process)"]
         NR["NodeRuntime"]
-        NED["NodeExecutionDriver"]
         SD["System Driver"]
         MAFS["ModuleAccessFileSystem"]
     end
@@ -80,8 +76,7 @@ flowchart TB
         BR["Bridge (ivm.Reference callbacks)"]
         MOD["Module Cache"]
     end
-    NR --> NED
-    NED --> ISO
+    NR --> ISO
     UC --> BR
     BR -->|"fs / net / process / crypto"| SD
     SD --> MAFS
@@ -95,7 +90,7 @@ flowchart TB
 - `SharedArrayBuffer` is unavailable in freeze mode
 
 **Outside the isolate (host):**
-- `NodeExecutionDriver` creates contexts, compiles modules, and manages the isolate lifecycle
+- The V8 isolate execution environment creates contexts, compiles modules, and manages the isolate lifecycle
 - `ModuleAccessFileSystem` overlays host `node_modules` at `/app/node_modules` (read-only, blocks `.node` native addons, prevents symlink escapes)
 - System driver applies permission checks before every host operation
 - Bridge enforces payload size limits on all transfers (`ERR_SANDBOX_PAYLOAD_TOO_LARGE`)
@@ -113,15 +108,13 @@ In the browser, the sandbox is a Web Worker.
 flowchart TB
     subgraph Host["Host (browser main thread)"]
         NR["NodeRuntime"]
-        BRD["BrowserRuntimeDriver"]
         SD["System Driver"]
     end
     subgraph WK["Web Worker"]
         UC["User Code (CJS / ESM)"]
         BR["Bridge (postMessage RPC)"]
     end
-    NR --> BRD
-    BRD -->|"postMessage"| WK
+    NR --> WK
     UC --> BR
     BR -->|"postMessage"| SD
 ```
@@ -133,43 +126,10 @@ flowchart TB
 - DNS operations return deterministic `ENOSYS` errors
 
 **Outside the worker (host):**
-- `BrowserRuntimeDriver` spawns workers, dispatches requests by ID, and correlates responses
+- The browser isolate spawns workers, dispatches requests by ID, and correlates responses
 - `createBrowserDriver()` configures OPFS or in-memory filesystem and fetch-based networking
 - Node-only runtime options (like `memoryLimit`) are validated and rejected at creation time
 
-## Python Runtime
-
-The Python sandbox runs Pyodide in a Node Worker thread.
-
-```mermaid
-flowchart TB
-    subgraph Host["Host (Node.js process)"]
-        PR["PythonRuntime"]
-        PRD["PyodideRuntimeDriver"]
-        SD["System Driver"]
-    end
-    subgraph WK["Worker Thread"]
-        PY["Pyodide (CPython via Emscripten)"]
-        UC["User Code (Python)"]
-        BR["Bridge (worker RPC)"]
-    end
-    PR --> PRD
-    PRD -->|"worker messages"| WK
-    UC --> BR
-    BR -->|"worker RPC"| SD
-```
-
-**Inside the worker:**
-- Pyodide loads once and keeps interpreter state warm across runs
-- Python code executes with access to bridged filesystem and network
-- stdio streams to the host via message events
-
-**Outside the worker (host):**
-- `PyodideRuntimeDriver` manages worker lifecycle and request correlation
-- Filesystem and network access goes through the same `SystemDriver` permission layer
-- On execution timeout, the worker state restarts for deterministic recovery
-- No `memoryLimit` or `timingMitigation` (Pyodide runs in a Worker, not a V8 isolate)
-
 ## Permission Flow
 
 Every capability request follows the same path regardless of runtime: