Copy link to headingWhy use a sandbox environment

The Claude Agent SDK operates as a long-running process that executes commands, manages files, and maintains conversational state. Because the SDK runs shell commands and modifies files on behalf of the AI agent, its important to isolate it in a sandboxed container. This prevents the agent from accessing your production systems, consuming unlimited resources, or interfering with other processes.

The SDK needs specific runtime dependencies installed before it can run:

• Claude Code CLI: Executes commands and manages the development environment
• Anthropic SDK: Provides the API client for Claude Code

Vercel Sandbox provides an ephemeral space with security, customization for dependencies, resource limits and isolation.

This guide shows you how to install the Claude Agent dependencies in a Vercel Sandbox and verify they work correctly before building your agent application.

Copy link to headingPrerequisites

Before you begin, make sure you have:

• Vercel CLI installed on your machine. If you don't have it, install it with npm install -g vercel
• Node.js 22 or later installed locally
• A Vercel project to link your sandbox to

Copy link to heading1. Project Setup

Create a new directory for your project and set up the required files:

The packages you installed:

• @vercel/sandbox: Vercel's SDK for creating and managing sandboxes
• ms: Helper for working with time durations
• Type definitions for TypeScript support

Update your package.json to enable ES modules by adding "type": "module":

Create a tsconfig.json file for TypeScript configuration:

Link your project to Vercel:

This command connects your local project to a new or existing Vercel project, which is required for sandbox authentication.

Copy link to heading2. Set Up Authentication

To securely connect your Vercel deployment with your sandbox, you can use the Vercel OIDC token automatically created with a project. Pull the authentication token to your local .env.local file:

This creates a .env.local file with a VERCEL_OIDC_TOKEN that the Vercel Sandbox SDK uses for authentication. The OIDC token expires after 12 hours, so you'll need to run vercel env pull again if you're developing for extended periods.

Copy link to heading3. Create the Installation Script

Create a new file called claude-sandbox.ts that sets up a Vercel Sandbox, installs both Claude Code CLI and the Anthropic SDK, and verifies the installation:

Copy link to headingWhat the script does

1. Creates a sandbox with 4 vCPUs and a 10-minute timeout
2. Installs Claude Code CLI globally using sudo for system-level access
3. Installs the Anthropic SDK in the working directory
4. Writes a verification script to the sandbox filesystem using writeFiles()with a Buffer
5. Runs the verification to confirm the SDK is properly connected
6. Stops the sandbox when complete

Copy link to headingScript reference information

• Uses sandbox.sandboxId to access the unique sandbox identifier
• Checks exit codes with != 0 for command failures
• Uses writeFiles()which accepts an array of file objects with content as a Buffer
• Streams output to process.stderr and process.stdout for real-time feedback

Copy link to heading4. Run the Verification

Run your script with the environment variables from .env.local:

The output should look similar to this:

To monitor your sandboxes in the Vercel dashboard:

1. Navigate to your project on vercel.com
2. Click the Observability tab
3. Click Sandboxes in the left sidebar
4. View sandbox history, command execution, and resource usage

The script automatically stops the sandbox after verification completes, but you can also manually stop sandboxes from the dashboard if needed.

Copy link to headingBest Practices

Copy link to headingAlways stop sandboxes

Always call sandbox.stop() when your work is complete to avoid unnecessary charges:

Copy link to headingSet appropriate timeouts

Configure timeouts based on your installation requirements. For simple dependency installation, 5-10 minutes is usually sufficient:

Copy link to headingNext Steps

Now that you've verified Claude Code CLI and Anthropic SDK work in Vercel Sandbox, you can:

1. Add API Authentication: Set up your Anthropic API key to enable agent execution
2. Build AI Features: Use the verified setup to build AI-powered code generation or analysis tools
3. Scale to Production: Deploy your sandbox-based AI applications

Copy link to headingConclusion

You've successfully installed Claude Code CLI and the Anthropic SDK in a Vercel Sandbox and verified they're properly connected. This setup confirms that your deployment environment can support Claude's Agent SDK.

Copy link to headingRelated Documentation