@bthn/codemode-local-executor

Local vm2-based executor for @cloudflare/codemode.

@cloudflare/codemode lets LLMs write executable TypeScript instead of making individual tool calls. It ships with DynamicWorkerExecutor which runs code inside a Cloudflare Worker — this package provides a drop-in replacement that runs the same code locally using Node.js vm2, so you can use codemode in any Node environment without a Workers deployment.

Installation

npm install @bthn/codemode-local-executor @cloudflare/codemode agents ai zod

Usage

Replace DynamicWorkerExecutor with NodeVMExecutor and everything else stays the same:

import { createCodeTool } from "@cloudflare/codemode/ai";
import { NodeVMExecutor } from "@bthn/codemode-local-executor";
import { streamText, tool } from "ai";
import { z } from "zod";

const tools = {
  getWeather: tool({
    description: "Get weather for a location",
    inputSchema: z.object({ location: z.string() }),
    execute: async ({ location }) => `Weather in ${location}: 72°F, sunny`,
  }),
  sendEmail: tool({
    description: "Send an email",
    inputSchema: z.object({
      to: z.string(),
      subject: z.string(),
      body: z.string(),
    }),
    execute: async ({ to, subject, body }) => `Email sent to ${to}`,
  }),
};

const executor = new NodeVMExecutor({
  env: {
    SOME_API_KEY: process.env.SOME_API_KEY ?? "",
  },
});

const codemode = createCodeTool({ tools, executor });

const result = streamText({
  model,
  system: "You are a helpful assistant.",
  messages,
  tools: { codemode },
});

Constructor options

new NodeVMExecutor(options?: NodeVMExecutorOptions)

| Option | Type | Default | Description | |--------|------|---------|-------------| | env | Record<string, string> | {} | Environment variables exposed inside the sandbox as process.env.* | | compiler | 'typescript' \| 'coffeescript' \| 'javascript' | 'typescript' | Compiler used to transpile the LLM-generated code before execution | | allowEval | boolean | false | Whether to allow eval() inside the sandbox | | allowWasm | boolean | false | Whether to allow WebAssembly inside the sandbox | | logCode | boolean | true | Log the generated code to stdout before executing (useful for debugging) |

How it works

1. createCodeTool generates TypeScript type definitions from your tools and builds a description the LLM can read.
2. The LLM writes an async arrow function that calls codemode.toolName(args).
3. NodeVMExecutor receives the code string and spins up a fresh NodeVM instance, injects the tool functions as codemode.*, and runs the snippet.
4. The result (or error) is returned as ExecuteResult — the executor never throws.

Security

vm2 provides V8-level isolation. The sandbox:

• Cannot access process.env beyond what you explicitly pass in env
• Cannot use eval or WebAssembly by default
• Console output is intercepted and returned in logs, not forwarded to host stdout

Note: vm2 is a best-effort sandbox. Do not use this to run untrusted code in production without additional hardening.

License

MIT