Runtime

How to add a code execution tool to the Vercel AI SDK

Pass runtimeTools(sbx) from withruntime/ai to generateText or streamText, and the model's commands run in a microVM.

Runtime's tools work with any model the AI SDK can call, and cost $0.03125 an hour per 2 vCPU, 4 GiB sandbox while the model thinks. runtimeTools(sbx) returns four AI SDK tools bound to one Firecracker microVM with its own Linux kernel: run a command, read a file, write a file, list a directory. The model picks commands and paths; your code picks the sandbox. The ai package was at 7.0.114 on npm on 25 September 2026; the adapter needs version 5 or later and was tested in the SDK's own loop with 7.0.87 on 23 September 2026.

Install

Terminalnpm install withruntime ainpx withruntime login

The login prints a link to approve in the browser, so there is no key to copy. In production, set RUNTIME_API_KEY from your secret store.

One call with tools

TypeScriptimport { generateText, stepCountIs, type LanguageModel } from "ai";import { Sandbox } from "withruntime";import { runtimeTools } from "withruntime/ai";export async function solve(model: LanguageModel, prompt: string) {  await using sbx = await Sandbox.create();  const { text } = await generateText({    model,    tools: runtimeTools(sbx),    stopWhen: stepCountIs(20),    prompt,  });  return text;}console.log(  await solve(    "anthropic/claude-sonnet-4.6",    "Download nothing. Compute 2**521 - 1 in Python and say if it is prime.",  ),);
  • stopWhen: stepCountIs(20) lets the model call tools and read the results for up to 20 steps. Without it, generateText makes one generation.
  • The model string is an AI Gateway id; a provider object such as one from @ai-sdk/openai works the same way.
  • await using stops the sandbox when solve returns.

The tools are runtime_exec, runtime_read_file, runtime_write_file and runtime_list_files (frameworks).

Stream from a route handler

A chat route streams while the model works. await using would stop the sandbox before the stream ends, so stop it in onFinish, and let the lease stop it if the client disconnects first:

TypeScriptimport { stepCountIs, streamText } from "ai";import { Sandbox } from "withruntime";import { runtimeTools } from "withruntime/ai";export async function POST(request: Request) {  const { prompt } = (await request.json()) as { prompt: string };  const sbx = await Sandbox.create({ timeoutSeconds: 600, onLeaseEnd: "stop" });  const result = streamText({    model: "anthropic/claude-sonnet-4.6",    tools: runtimeTools(sbx, { timeoutSeconds: 120, maxOutputChars: 8_000 }),    stopWhen: stepCountIs(20),    prompt,    onFinish: async () => {      await sbx.stop();    },  });  return result.toTextStreamResponse();}

timeoutSeconds is the default for a command the model starts without one (300 otherwise), and maxOutputChars cuts each of stdout, stderr and a file read from the front, keeping the end, where errors usually are.

Built-in code execution in the AI SDK, compared

The AI SDK has other ways to run code. What each is, from the AI SDK docs read on 25 September 2026:

Option Where code runs Models What the docs say
openai.tools.codeInterpreter() OpenAI's hosted container OpenAI "allows models to write and execute Python code"
anthropic.tools.codeExecution_20260120 Anthropic's container Claude "gives Claude direct access to a real Python environment"
openai.tools.localShell() Your own machine OpenAI Runs "shell commands locally on a machine you or the user provides"
ai-sdk-tool-code-execution Vercel Sandbox Any Python 3.13 in "an isolated environment"
experimental_sandbox Wherever your implementation sends it Any "does not sandbox the tool itself"; tool code runs "in your application process"
runtimeTools(sbx) A Runtime microVM your code owns Any Shell, files and listings in Ubuntu 24.04, with Python, Node.js, Bun and gcc

Provider tools lock the choice of model to the provider that runs the container. Runtime's tools are ordinary AI SDK tools, so switching models is a one-word change. For prices of the hosted containers, see OpenAI Code Interpreter alternative and Claude code execution tool alternative.

What the model can do in the sandbox

The sandbox is a full Linux machine with sudo, so the model can pip install, npm install, compile C, run a test suite or start a server. Your code holds sbx and can add more between steps or turns:

  • Show the user what was built. sbx.previews.create(3000) shares a port at a private HTTPS address under runtimehost.com (share a port).
  • Keep a session across chat turns. Sandbox.getOrCreate("chat-42") returns the same sandbox for the same name, woken if it was paused, so a user's files survive between requests (sandboxes by name).
  • Pause when idle. idlePauseSeconds: 600 pauses after ten quiet minutes, with memory kept, and the next tool call wakes it in about half a second.
  • Branch. sbx.fork({ count: 3 }) makes three running copies to try three fixes at once (snapshots and forks).
  • Notebook-style cells. sbx.interpreter.run(code) keeps variables between calls and returns charts as PNG, for a data chat (code interpreter for chatbots).

Keep keys and spending safe

The model provider's key never enters the sandbox: generateText runs in your server and sends the sandbox only commands. To bound the sandbox:

  • maxCostMicros on Sandbox.create refuses a sandbox whose first lease would cost more, in microdollars.
  • A daily spending limit on the Runtime key stops creates, wakes and extensions past it with spending_limit_reached (HTTP 402), and nothing is charged (read-only keys and daily limits).
  • A read-only key for the admin page that lists sandboxes and their cost.
  • network at create, such as { internet: true, allow: ["registry.npmjs.org"] }, or { internet: false } for pure computation. The host enforces it, root included.
  • Secrets for tokens the model's code needs: the sandbox sees a placeholder, and the host adds the value on HTTPS requests to the hosts you name (secrets).

What it costs

CPU is billed as used at $0.025 per vCPU-hour, with a floor of a twentieth of a vCPU, and memory at $0.0075 per GiB-hour, so a sandbox that waits on the model costs little. With both CPUs busy, 2 vCPU and 4 GiB is $0.08 an hour (pricing). New accounts get 50 free sandbox hours, no card. Mastra agents take these same tools; see Mastra.

Sources

Checked 25 September 2026.

Facts on this page were checked on 25 September 2026.

Claim 50 hours free