Experimental_SandboxSession

The Experimental_SandboxSession interface describes an execution environment that tools can use to run commands. Pass an experimental sandbox using the experimental_sandbox option to generateText, streamText, ToolLoopAgent.generate, ToolLoopAgent.stream, or agent UI stream helpers to make it available to tool description functions and tool execution.

This API is experimental and can change in patch releases. Passing an experimental sandbox does not sandbox the tool itself. Tool code still runs in your application process unless the tool explicitly delegates work to the experimental sandbox.

Import 

import type { Experimental_SandboxSession } from "ai"

Type Definition 

type Experimental_SandboxSession = {
  readonly description: string;
  readonly run: (options: {
    command: string;
    workingDirectory?: string;
    env?: Record<string, string>;
    abortSignal?: AbortSignal;
  }) => PromiseLike<{
    exitCode: number;
    stdout: string;
    stderr: string;
  }>;
};

Properties

description:

string

run:

(options: { command: string; workingDirectory?: string; env?: Record<string, string>; abortSignal?: AbortSignal }) => PromiseLike<{ exitCode: number; stdout: string; stderr: string }>
options

command:

string

workingDirectory:

string | undefined

env:

Record<string, string> | undefined

abortSignal:

AbortSignal | undefined

Example 

const result = await generateText({
  model: "xai/grok-4.5",
  tools: { shell },
  experimental_sandbox,
  prompt: 'Run the test suite.',
});

Inside a tool, read the experimental sandbox from the second execute argument:

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,
    });
  },
});

See Also