Skip to content
Runtime

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

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

Start free, no cardRead as Markdown

Runtime's tools work with any model the AI SDK can call. They 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.153 on npm on 25 October 2026. The adapter needs version 5 or later. It 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 deletes 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 delete the sandbox before the stream ends. So stop the sandbox in onFinish, and let its time limit 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). 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. The table lists each one, from the AI SDK docs read on 25 October 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 limit 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. The model can therefore run pip install, npm install, compile C, run a test suite or start a server. Your code holds sbx. It 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. A user's files survive between requests (sandboxes by name).
  • Pause when idle. idlePauseSeconds: 600 pauses the sandbox after ten quiet minutes, with memory kept.
  • Branch. sbx.fork({ count: 3 }) makes three running copies, so you can try three fixes at the same time (snapshots and forks).
  • Notebook-style cells. sbx.interpreter.run(code) keeps variables between calls. It 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 on your server and sends the sandbox only commands. To limit the sandbox:

  • maxTotalCostMicros on Sandbox.create stops a sandbox once its total cost passes the limit, 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. 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. Memory is billed at $0.0075 per GiB-hour. A sandbox that waits on the model therefore costs little. With both CPUs busy, 2 vCPU and 4 GiB is $0.08 an hour (pricing). A new account gets 100 free hours of a 1 GB machine in its first 30 days, no card. Mastra agents take these same tools; see Mastra. To run a whole coding agent (Claude Code, Codex, OpenCode or Pi) under the AI SDK's HarnessAgent in a sandbox, see AI SDK HarnessAgent and the Vercel AI SDK guide.

Sources

Checked 25 October 2026.

Facts on this page were checked on 25 October 2026.

Related.

100 free hoursin your first 30 days.

of a 1 GB machine

  • No credit card
  • Four sandboxes at once, 2 vCPU and 4 GiB each
  • Then prepaid credit from $10, no plan fee
Start free, no card
Start free, no card