Vercel Ships a Bash Tool That Gives AI Agents Real Shell Access

Vercel has added a first-party Bash tool to its AI SDK, giving tool-calling models access to a shell within an agent loop. Developers use one tool interface while choosing whether commands run in memory, in Vercel Sandbox, or through a custom sandbox implementation.

The @ai-sdk/tool-bash package works with generateText, streamText, and ToolLoopAgent. Its experimental_createBashTool function lets agents search, inspect, and transform files through Bash commands. The package has no direct dependency on a specific execution runtime.

Pick your blast radius

The runtime adapter determines the tool’s capabilities, startup cost, and isolation. Developers can begin with @ai-sdk/sandbox-just-bash, move production workloads to @ai-sdk/sandbox-vercel, or implement the compatible sandbox session interface themselves.

For lightweight work, just-bash provides a TypeScript shell interpreter and virtual filesystem inside the Node.js process. It avoids spawning shell processes or running arbitrary native binaries, which reduces startup overhead for file transformation, log parsing, and retrieval-augmented generation preprocessing.

Workloads that require native binaries, network access, or stronger isolation can use Vercel Sandbox. Changing runtimes affects session creation and lifecycle management, while the Bash tool definition and model-facing schema remain the same.

A five-step agent loop

import {
  createJustBashNetworkSandboxSession,
} from '@ai-sdk/sandbox-just-bash';
import {
  experimental_createBashTool as createBashTool,
} from '@ai-sdk/tool-bash';
import { generateText, isStepCount } from 'ai';

const session = await createJustBashNetworkSandboxSession();
const sandbox = session.restricted();

await sandbox.writeTextFile({
  path: 'notes.txt',
  content: 'Apples: 10\nPears: 20\n',
});

const bash = await createBashTool({ sandbox });

const result = await generateText({
  model,
  tools: { bash },
  stopWhen: isStepCount(5),
  prompt: 'Read notes.txt and write a summary to summary.txt.',
});

console.log(result.text);

The model sends { command: string } and receives { stdout, stderr, exitCode }. A nonzero exit code gives the model enough information to inspect a failure and attempt a correction. The isStepCount(5) condition separately limits the agent loop to five model steps.

Standard output and error are capped at 30,000 characters per stream by default. Longer output receives a truncation notice, preventing commands such as find / from consuming an excessive share of the model’s context window.

Controls worth setting

The caller owns the sandbox lifecycle, including creation, reconnection, and destruction. Tools that share a session also share its filesystem, allowing a Bash tool and custom file tools to operate on the same workspace. Shell state and files persist only according to the selected runtime’s session behavior.

Why the abstraction matters

A shared sandbox session interface centralizes command execution, timeouts, output truncation, cancellation, and filesystem access. Developers can test with an in-process interpreter and deploy against an isolated virtual machine without changing the schema presented to the model.

Shell access also reduces the amount of file content that applications must place directly in prompts. An agent can locate relevant files with commands such as find and grep, inspect selected sections, and return only the material needed for the current task.

The tool can run through Vercel’s AI Gateway or with another AI SDK provider. Compatibility depends on the selected model’s support for tool calling and its ability to generate suitable shell commands.

Good fits and hard limits

• Repository analysis: Search and inspect source trees without loading entire projects into model context.
• Log and data processing: Use tools such as awk and jq instead of chaining many narrow tool calls.
• Build and test agents: Run commands against an isolated scratch workspace.
• Filesystem-based retrieval: Let an agent navigate files on demand rather than preloading or pre-chunking every document.

Just-bash provides a lightweight execution environment within the application process, without a virtual-machine or container security boundary. Commands influenced by untrusted users should run in a hardened sandbox with restricted credentials, filesystem access, networking, CPU time, and memory. Model instructions alone do not enforce those controls.

Install and version requirements

The packages require Node.js 22.13 or newer and can be installed with the following command:

pnpm add ai @ai-sdk/tool-bash @ai-sdk/sandbox-just-bash

The Bash tool and sandbox session interface remain experimental. The experimental_ prefix signals that names and contracts may change before the API stabilizes.