Open History to see the last commit
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>
308}
309
310interface IsolateConfig {
311 bindings: Record<string, ToolBinding>
312 timeout?: number
313 memoryLimit?: number
314}
315
316interface IsolateContext {
317 execute(code: string): Promise<ExecutionResult>
318 dispose(): Promise<void>
319}
320
321interface ExecutionResult<T = unknown> {
322 success: boolean
323 value?: T
324 logs: Array<string>
325 error?: NormalizedError
326}
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