Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

code-mode-isolates.md

336 lines16.1 KB

1---
2title: Code Mode Isolate Drivers
3id: code-mode-isolates
4order: 4
5description: "Compare Code Mode sandbox drivers — Node isolated-vm, QuickJS WASM, QuickJS Bun (bun:ffi), Cloudflare Workers, and Daytona sandboxes — and choose the right runtime for your deployment."
6keywords:
7 - tanstack ai
8 - code mode
9 - isolate driver
10 - isolated-vm
11 - quickjs
12 - quickjs-bun
13 - bun
14 - bun:ffi
15 - cloudflare workers
16 - daytona
17 - sandbox
18 - secure execution
19---
20​
21Isolate drivers provide the secure sandbox runtimes that [Code Mode](./code-mode.md) uses to execute generated TypeScript. All drivers implement the same `IsolateDriver` interface, so you can swap them without changing any other code.
22​
23## Choosing a Driver
24​
25​
26| | Node (`isolated-vm`) | QuickJS (WASM) | QuickJS Bun (`bun:ffi`) | Cloudflare Workers | Daytona |
27| -------------------- | ------------------------ | --------------------------- | ------------------------ | ------------------------------ | ---------------------------------- |
28| **Best for** | Server-side Node.js apps | Browsers, edge, portability | Bun servers | Edge deployments on Cloudflare | Full remote Linux sandboxes |
29| **Performance** | Fast (V8 JIT) | Slower (interpreted) | Fast (native QuickJS) | Fast (V8 on Cloudflare edge) | Fast (native runtime; remote call) |
30| **Native deps** | Yes (C++ addon) | None | None (TinyCC on the fly) | None | None |
31| **Browser support** | No | Yes | No (Bun only) | N/A | Yes |
32| **Memory limit** | Configurable | Configurable | Configurable | N/A | Configurable |
33| **Stack size limit** | N/A | Configurable | Configurable | N/A | N/A |
34| **Setup** | `pnpm add` | `pnpm add` | `bun add` | Deploy a Worker first | Create or pass a Daytona sandbox |
35​
36​
37---
38​
39## Node.js Driver (`@tanstack/ai-isolate-node`)
40​
41Uses V8 isolates via the [`isolated-vm`](https://github.com/laverdet/isolated-vm) native addon. This is the fastest option for server-side Node.js applications because generated code runs in the same V8 engine as the host, under JIT compilation, with no serialization overhead beyond tool call boundaries.
42​
43### Installation
44​
45```bash
46pnpm add @tanstack/ai-isolate-node
47```
48​
49`isolated-vm` is a native C++ addon and must be compiled for your platform. It requires Node.js 18 or later.
50​
51### Usage
52​
53```typescript
54import { createNodeIsolateDriver } from '@tanstack/ai-isolate-node'
55​
56const driver = createNodeIsolateDriver({
57 memoryLimit: 128, // MB
58 timeout: 30_000, // ms
59})
60```
61​
62### Options
63​
64​
65| Option | Type | Default | Description |
66| ------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
67| `memoryLimit` | `number` | `128` | Maximum heap size for the V8 isolate, in megabytes. Execution is terminated if this limit is exceeded. |
68| `timeout` | `number` | `30000` | Maximum wall-clock time per execution, in milliseconds. |
69​
70​
71### How it works
72​
73Each `execute_typescript` call creates a fresh V8 isolate. Your tools are bridged into the isolate as async reference functions — when generated code calls `external_myTool(...)`, the call crosses the isolate boundary back into the host Node.js process, executes your tool implementation, and returns the result. Console output (`log`, `error`, `warn`, `info`) is captured and returned in the execution result. The isolate is destroyed after each call.
74​
75---
76​
77## QuickJS Driver (`@tanstack/ai-isolate-quickjs`)
78​
79Uses [QuickJS](https://bellard.org/quickjs/) compiled to WebAssembly via Emscripten. Because the sandbox is a WASM module, it has no native dependencies and runs anywhere JavaScript runs: Node.js, browsers, Deno, Bun, and Cloudflare Workers (without deploying a separate Worker).
80​
81### Installation
82​
83```bash
84pnpm add @tanstack/ai-isolate-quickjs
85```
86​
87### Usage
88​
89```typescript
90import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
91​
92const driver = createQuickJSIsolateDriver({
93 memoryLimit: 128, // MB
94 timeout: 30_000, // ms
95 maxStackSize: 524288, // bytes (512 KiB)
96})
97```
98​
99### Options
100​
101​
102| Option | Type | Default | Description |
103| -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
104| `memoryLimit` | `number` | `128` | Maximum heap memory for the QuickJS VM, in megabytes. |
105| `timeout` | `number` | `30000` | Maximum wall-clock time per execution, in milliseconds. |
106| `maxStackSize` | `number` | `524288` | Maximum call stack size in bytes (default: 512 KiB). Increase for deeply recursive code; decrease to catch runaway recursion sooner. |
107​
108​
109### How it works
110​
111QuickJS WASM uses an asyncified execution model — the WASM module can pause while awaiting host async functions (your tools). Executions are serialized through a global queue to prevent concurrent WASM calls, which the asyncify model does not support. Fatal errors (memory exhaustion, stack overflow) are detected, the VM is disposed, and a structured error is returned. Console output is captured and returned with the result.
112​
113> **Performance note:** QuickJS interprets JavaScript rather than JIT-compiling it, so compute-heavy scripts run slower than with the Node driver. For typical LLM-generated scripts that are mostly waiting on `external_*` tool calls, this difference is not significant.
114​
115---
116​
117## QuickJS Bun Driver (`@tanstack/ai-isolate-quickjs-bun`)
118​
119Runs [QuickJS](https://bellard.org/quickjs/) natively on the [Bun](https://bun.sh/) runtime through `bun:ffi`, via the [`quickjs-bun`](https://github.com/superpowerdotcom/quickjs-bun) package. There are no native dependencies and no build step — the vendored QuickJS C sources are compiled on the fly with Bun's embedded TinyCC, once per process. This makes it the fastest sandboxed option for Code Mode on Bun.
120​
121### Installation
122​
123```bash
124bun add @tanstack/ai-isolate-quickjs-bun
125```
126​
127Requires Bun 1.3.14 or later. On Windows, provide a prebuilt QuickJS dynamic library via the `QUICKJS_BUN_NATIVE_LIBRARY` environment variable.
128​
129### Usage
130​
131```typescript
132import { createQuickJSBunIsolateDriver } from '@tanstack/ai-isolate-quickjs-bun'
133​
134const driver = createQuickJSBunIsolateDriver({
135 memoryLimit: 128, // MB
136 timeout: 30_000, // ms
137 maxStackSize: 524288, // bytes (512 KiB)
138})
139```
140​
141### Options
142​
143​
144| Option | Type | Default | Description |
145| -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
146| `memoryLimit` | `number` | `128` | Maximum heap memory for the QuickJS runtime, in megabytes. |
147| `timeout` | `number` | `30000` | Maximum wall-clock time per execution, in milliseconds. |
148| `maxStackSize` | `number` | `524288` | Maximum call stack size in bytes (default: 512 KiB). Increase for deeply recursive code; decrease to catch runaway recursion sooner. |
149| `maxToolCalls` | `number` | `1000` | Maximum host tool calls per execution. Bounds output and memory growth from untrusted sandbox code that fans out (e.g. `Promise.all` over a huge array); exceeding it throws a catchable error inside the sandbox. |
150​
151​
152### How it works
153​
154Each context gets a dedicated native QuickJS runtime with its own memory limit, stack size, and interrupt-based timeout, so contexts execute independently — unlike the WASM driver, which serializes all executions through one shared asyncified WASM module. Fatal errors (memory exhaustion, stack overflow) are detected, the VM is disposed, and a structured error is returned; create a fresh context afterwards. A per-execution `maxToolCalls` budget bounds host tool-call fan-out. Console output is captured and returned with the result.
155​
156> **Bun only:** This driver requires Bun 1.3.14 or later and throws a descriptive error when creating a context on Node.js — use the Node or QuickJS WASM driver there. On Bun, prefer this driver over the WASM one: it runs QuickJS natively, and quickjs-emscripten's asyncify bridge is unreliable for async host tool calls under Bun.
157​
158---
159​
160## Cloudflare Workers Driver (`@tanstack/ai-isolate-cloudflare`)
161​
162Runs generated code inside a [Cloudflare Worker](https://workers.cloudflare.com/) at the edge. Your application server sends code and tool schemas to the Worker via HTTP; the Worker executes the code and calls back when it needs a tool result. This keeps your tool implementations on your server while sandboxed execution happens on Cloudflare's global network.
163​
164### Installation
165​
166```bash
167pnpm add @tanstack/ai-isolate-cloudflare
168```
169​
170### Usage
171​
172```typescript
173import { createCloudflareIsolateDriver } from '@tanstack/ai-isolate-cloudflare'
174​
175const driver = createCloudflareIsolateDriver({
176 workerUrl: 'https://my-code-mode-worker.my-account.workers.dev',
177 authorization: process.env.CODE_MODE_WORKER_SECRET,
178 timeout: 30_000,
179 maxToolRounds: 10,
180})
181```
182​
183### Options
184​
185​
186| Option | Type | Default | Description |
187| --------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
188| `workerUrl` | `string` | — | **Required.** Full URL of the deployed Cloudflare Worker. |
189| `authorization` | `string` | — | Optional value sent as the `Authorization` header on every request. Use this to prevent unauthorized access to your Worker. |
190| `timeout` | `number` | `30000` | Maximum wall-clock time for the entire execution (including all tool round-trips), in milliseconds. |
191| `maxToolRounds` | `number` | `10` | Maximum number of tool-call/result cycles per execution. Prevents infinite loops when generated code calls tools in a loop. |
192​
193​
194### Deploying the Worker
195​
196The package exports a ready-made Worker handler at `@tanstack/ai-isolate-cloudflare/worker`. Create a `wrangler.toml` and a worker entry file:
197​
198```toml
199# wrangler.toml
200name = "code-mode-worker"
201main = "src/worker.ts"
202compatibility_date = "2024-01-01"
203​
204[unsafe]
205bindings = [{ name = "eval", type = "eval" }]
206```
207​
208```typescript
209// src/worker.ts
210export { default } from '@tanstack/ai-isolate-cloudflare/worker'
211```
212​
213Deploy:
214​
215```bash
216wrangler deploy
217```
218​
219### How it works
220​
221The driver implements a request/response loop for tool execution:
222​
223```
224Driver (your server) Worker (Cloudflare edge)
225───────────────────── ─────────────────────────
226Send: code + tool schemas ──────▶ Execute code
227 ◀────── Return: needs tool X with args Y
228Execute tool X locally
229Send: tool result ──────▶ Resume execution
230 ◀────── Return: final result / needs tool Z
231...repeat until done...
232```
233​
234Each round-trip adds network latency, so the `maxToolRounds` limit both prevents runaway scripts and caps the maximum number of cross-continent hops. Console output from all rounds is aggregated and returned in the final result.
235​
236> **Security:** The Worker requires `UNSAFE_EVAL` (local dev) or the `eval` unsafe binding (production) to execute arbitrary code. Restrict access using the `authorization` option or Cloudflare Access policies.
237​
238---
239​
240## Daytona Driver (`@tanstack/ai-isolate-daytona`)
241​
242Runs generated code inside a Daytona sandbox through `sandbox.process.codeRun`. Your application process still owns TanStack tool implementations; the Daytona sandbox only receives wrapped generated code plus replayed tool results.
243​
244### Installation
245​
246```bash
247pnpm add @tanstack/ai-isolate-daytona
248```
249​
250If your application creates sandboxes with the official Daytona SDK, also install it:
251​
252```bash
253pnpm add @daytona/sdk
254```
255​
256### Usage
257​
258```typescript
259import { Daytona } from '@daytona/sdk'
260import { createDaytonaIsolateDriver } from '@tanstack/ai-isolate-daytona'
261​
262const daytona = new Daytona()
263const sandbox = await daytona.create({ language: 'typescript' })
264​
265const driver = createDaytonaIsolateDriver({
266 sandbox,
267 timeout: 30_000,
268 maxToolRounds: 10,
269})
270```
271​
272### Options
273​
274| Option | Type | Default | Description |
275|--------|------|---------|-------------|
276| `sandbox` | `DaytonaSandboxLike` | — | **Required.** A caller-owned Daytona sandbox-like object with `process.codeRun(code, params?, timeout?)`. |
277| `timeout` | `number` | `30000` | Maximum wall-clock time for the entire execution, including replay rounds, in milliseconds. |
278| `maxToolRounds` | `number` | `10` | Maximum number of sandbox <-> host tool callback rounds. Prevents infinite loops when generated code repeatedly asks for tools. |
279​
280### How it works
281​
282The driver uses the same host-owned tool replay shape as the Cloudflare driver without Cloudflare's parent Worker / Dynamic Worker split:
283​
284```text
285Driver (your server) Daytona sandbox
286───────────────────── ───────────────
287Send: wrapped code ──────▶ Execute with process.codeRun
288 ◀────── Return: need_tools with tool requests
289Execute tools locally
290Replay with toolResults ──────▶ Continue execution
291 ◀────── Return: final result / more tool requests
292...repeat until done...
293```
294​
295Use this driver when you want Code Mode execution in a full Daytona sandbox instead of an in-process isolate, QuickJS WASM runtime, or Cloudflare Worker. The sandbox should use a language/runtime capable of executing the JavaScript emitted by Code Mode, and your application remains responsible for sandbox lifecycle, filesystem, network, cleanup, and secret policy. Creating a Code Mode context does not create or delete a Daytona sandbox.
296​
297---
298​
299## The `IsolateDriver` Interface
300​
301All provided drivers satisfy this interface, exported from `@tanstack/ai-code-mode`:
302​
303```typescript
304import type { ToolBinding, NormalizedError } from "@tanstack/ai-code-mode";
305​
306interface IsolateDriver {
307 createContext(config: IsolateConfig): Promise<IsolateContext>
309​
310interface IsolateConfig {
311 bindings: Record<string, ToolBinding>
312 timeout?: number
313 memoryLimit?: number
315​
316interface IsolateContext {
317 execute(code: string): Promise<ExecutionResult>
318 dispose(): Promise<void>
320​
321interface ExecutionResult<T = unknown> {
322 success: boolean
323 value?: T
324 logs: Array<string>
325 error?: NormalizedError
327```
328​
329You can implement this interface to build a custom driver — for example, a Docker-based sandbox or a Deno subprocess.
330​
331## Next Steps
332​
333- [Code Mode](./code-mode) — Core setup, API reference, and getting started guide
334- [Showing Code Mode in the UI](./client-integration) — Display execution progress in your React app
335- [Code Mode with Skills](./code-mode-with-skills) — Add persistent, reusable skill libraries
336​