Sandbox

Purpose and Scope

A sandbox is the execution environment that AI SDK tools can explicitly delegate work to when a model needs help running commands or code. In the AI SDK docs this is exposed as the experimental sandbox setting, named experimental_sandbox, on generateText, streamText, and ToolLoopAgent-style calls. The primitive matters because tool calling often crosses from language generation into side effects: listing files, running a shell command, executing a script, or inspecting a project workspace. The sandbox gives those delegated operations a separate environment while keeping the AI SDK tool contract provider-agnostic. Sources: content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

This page covers sandbox from the perspective of a developer building tools. It does not redefine tool calling; instead, it explains where sandbox fits into the existing tool lifecycle. A tool is an object with a description, input schema, optional execute function, and optional strict mode. The source documentation explicitly says descriptions can be functions derived from tool context and the experimental sandbox, and that execute functions produce tool results after receiving validated tool-call inputs. Sandbox participates in both of those places: it can help describe the environment to the model, and it can run delegated operations during execution. Sources: content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

The most important constraint is that passing a sandbox does not sandbox the tool function itself. Tool code still runs wherever the application runs: a server route, script, worker, agent runtime, or other host process. Only operations that the tool explicitly sends to the sandbox, such as calling experimental_sandbox.run(...), execute in the sandbox environment. Treat the sandbox as a capability handed to trusted tool code, not as a magic isolation wrapper around arbitrary JavaScript or TypeScript in your application.

Relevant Source Files

• content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx — Defines tool calling concepts, the tool object shape, dynamic descriptions, how tools are passed to generateText and streamText, and how tool description functions can receive both toolsContext and experimental_sandbox.

Core Primitive Model

The sandbox primitive is easiest to understand beside the other tool primitives. A tool description tells the model when and how the tool should be used. An input schema validates the model’s proposed arguments. An execute function performs work after the model emits a tool call. toolsContext provides per-tool typed context, such as a project name or tenant identifier. experimental_sandbox is a separate request-level capability that can be made available to description functions and execute functions when a tool needs an execution environment. Sources: content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

Because descriptions can be functions, a sandbox can affect what the model sees before it chooses a tool. The documentation’s dynamic description pattern builds a shell tool description from both the typed tool context and the current sandbox description. That lets a tool say, for example, that it runs commands for a specific project and include sandbox-specific details when they exist. This is intentionally explicit: the sandbox description is not automatically injected into the model prompt. If the model should know root directories, exposed ports, hostnames, or environment expectations, add that information to instructions, a system prompt, user-visible context, or a tool description function.

Execution Flow

A typical sandbox-backed tool flow starts with a normal AI SDK generation call. The application calls generateText or streamText, selects a model, passes a tools object, and includes the experimental_sandbox setting. The model receives tool definitions derived from the tool descriptions and input schemas. If it emits a tool call, the AI SDK validates the tool-call input against the schema and invokes the tool’s execute function when one is present. The execute function receives the parsed input as its first parameter and execution options, including the sandbox when provided, as its second parameter. Sources: content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

Inside the execute function, the tool should check that a sandbox exists before relying on it. The official example throws an error when experimental_sandbox is unavailable, then delegates the command, working directory, and abort signal to experimental_sandbox.run. That check is a practical boundary: the same tool definition may be reused in contexts where a sandbox is not configured, where tool calls are forwarded to another system, or where execution happens on the client or in a queue. The tool owns the decision to require sandbox support or provide a fallback.

import { generateText, tool } from 'ai';
import { z } from 'zod';
 
const shell = tool({
  inputSchema: z.object({
    command: z.string(),
    workingDirectory: z.string().optional(),
  }),
  execute: async (
    { command, workingDirectory },
    { abortSignal, experimental_sandbox },
  ) => {
    if (!experimental_sandbox) {
      throw new Error('Experimental sandbox is not available');
    }
 
    return experimental_sandbox.run({
      command,
      workingDirectory,
      abortSignal,
    });
  },
});
 
const result = await generateText({
  model,
  tools: { shell },
  experimental_sandbox,
  prompt: 'List the files in the project.',
});

API Components

The public surface described by the docs is intentionally compact. The call-level option is experimental_sandbox. Tool description functions can receive it alongside the matching tool context. Tool execute functions can receive it through their second parameter. The sandbox’s run operation accepts a command, and the official docs also describe optional workingDirectory, env, and abortSignal fields. Use workingDirectory when the command should run somewhere other than the sandbox implementation’s default directory. Use env for command-specific environment variables. Forward abortSignal so cancellation in the generation or agent loop can stop sandbox work promptly.

System-to-Code Mapping

The repository documentation places sandbox in the Tool Calling page rather than in a standalone provider page, which is an important design signal. Sandbox is not a model provider, a UI transport, or a prompt format. It is a tool-loop capability that complements validated tool calls. The same page defines ordinary tools, dynamic descriptions, and multi-step behavior, so developers encounter sandbox at the point where they are already deciding whether a tool should execute server-side, be forwarded elsewhere, or call into another execution substrate. Sources: content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

Dynamic descriptions connect sandbox to model planning, while execute options connect it to side effects. If prepareStep changes toolsContext or experimental_sandbox, the next generation step uses the updated values when resolving tool descriptions. That means multi-step systems can alter the visible tool environment as the loop progresses, such as switching projects, narrowing a workspace, or changing the sandbox capability. The model still only sees what the developer exposes through descriptions, prompts, or instructions; the sandbox object itself is not automatically serialized into the prompt.

Safety and Operational Guidance

Use sandbox as a narrowly delegated capability. A shell tool should validate its schema, decide which commands it is willing to run, and pass only the intended operation to the sandbox. Do not assume that the presence of experimental_sandbox makes the surrounding application process safe from malicious tool logic, unsafe command construction, or excessive privileges. The application is still responsible for defining tool boundaries, deciding what context to reveal, and handling tool results carefully before returning them to a user or feeding them into later model steps.

For cancellation, propagate abortSignal from the tool execution options into experimental_sandbox.run. This keeps long-running commands aligned with the AI SDK call lifecycle, especially in streaming and agent flows where users may cancel a request or a loop may stop early. For environment-specific behavior, prefer explicit workingDirectory and env values over hidden assumptions. If the model needs to reason about those values, include them deliberately in a description function or prompt rather than relying on implicit host-side configuration.

Next Steps

After wiring a sandbox-backed tool, test it like any other tool-loop integration: verify that the input schema rejects bad arguments, confirm the tool handles a missing sandbox, exercise cancellation, and inspect the resulting tool result shape. Then connect the concept to adjacent AI SDK primitives. Read the tool-calling guide for multi-step execution and strict mode, the runtime and tool context material for request-scoped data boundaries, and the agent call-options material when sandbox selection should vary per request or per agent invocation.