Using Vercel Sandbox to run Claude’s Agent SDK

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.

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

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

1
mkdir claude-sandbox-demo
2
cd claude-sandbox-demo
3
npm init -y
4
npm install @vercel/sandbox ms
5
npm install -D @types/ms @types/node

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":

1
{
2
  "name": "claude-sandbox-demo",
3
  "type": "module",
4
  "dependencies": {
5
    "@vercel/sandbox": "^1.0.2",
6
    "ms": "^2.1.3"
7
  },
8
  "devDependencies": {
9
    "@types/ms": "^2.1.0",
10
    "@types/node": "^24.10.0"
11
  }
12
}

Create a tsconfig.json file for TypeScript configuration:

1
{
2
  "compilerOptions": {
3
    "module": "ES2022",
4
    "moduleResolution": "node",
5
    "esModuleInterop": true,
6
    "types": ["node"]
7
  }
8
}

Link your project to Vercel:

1
vercel link

This command connects your local project to a new or existing Vercel project, which is required for sandbox 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:

1
vercel env pull

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.

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:

1
import ms from 'ms';
2
import { Sandbox } from '@vercel/sandbox';
3

4
async function main() {
5
  const sandbox = await Sandbox.create({
6
    resources: { vcpus: 4 },
7
    // Timeout in milliseconds: ms('10m') = 600000
8
    // Defaults to 5 minutes. The maximum is 5 hours for Pro/Enterprise, and 45 minutes for Hobby.
9
    timeout: ms('10m'),
10
    runtime: 'node22',
11
  });
12

13
  console.log(`Sandbox created: ${sandbox.sandboxId}`);
14
  console.log(`Installing Claude Code CLI...`);
15

16
  // Install Claude Code CLI globally
17
  const installCLI = await sandbox.runCommand({
18
    cmd: 'npm',
19
    args: ['install', '-g', '@anthropic-ai/claude-code'],
20
    stderr: process.stderr,
21
    stdout: process.stdout,
22
    sudo: true,
23
  });
24

25
  if (installCLI.exitCode != 0) {
26
    console.log('installing Claude Code CLI failed');
27
    process.exit(1);
28
  }
29

30
  console.log(`✓ Claude Code CLI installed`);
31
  console.log(`Installing Anthropic SDK...`);
32

33
  // Install @anthropic-ai/sdk in the working directory
34
  const installSDK = await sandbox.runCommand({
35
    cmd: 'npm',
36
    args: ['install', '@anthropic-ai/sdk'],
37
    stderr: process.stderr,
38
    stdout: process.stdout,
39
  });
40

41
  if (installSDK.exitCode != 0) {
42
    console.log('installing Anthropic SDK failed');
43
    process.exit(1);
44
  }
45

46
  console.log(`✓ Anthropic SDK installed`);
47
  console.log(`Verifying SDK connection...`);
48

49
  // Create a simple script to verify the SDK can be imported
50
  const verifyScript = `
51
import Anthropic from '@anthropic-ai/sdk';
52

53
console.log('SDK imported successfully');
54
console.log('Anthropic SDK version:', Anthropic.VERSION);
55
console.log('SDK is ready to use');
56
`;
57

58
  await sandbox.writeFiles([
59
    {
60
      path: '/vercel/sandbox/verify.mjs',
61
      content: Buffer.from(verifyScript),
62
    },
63
  ]);
64

65
  // Run the verification script
66
  const verifyRun = await sandbox.runCommand({
67
    cmd: 'node',
68
    args: ['verify.mjs'],
69
    stderr: process.stderr,
70
    stdout: process.stdout,
71
  });
72

73
  if (verifyRun.exitCode != 0) {
74
    console.log('SDK verification failed');
75
    process.exit(1);
76
  }
77

78
  console.log(`✓ Anthropic SDK is properly connected`);
79
  console.log(`\\nSuccess! Both Claude Code CLI and Anthropic SDK are installed and ready to use.`);
80

81
  // Stop the sandbox
82
  await sandbox.stop();
83
  console.log(`Sandbox stopped`);
84
}
85

86
main().catch(console.error);
87

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

• 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

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

1
node --env-file .env.local --experimental-strip-types ./claude-sandbox.ts 

The output should look similar to this:

1
Sandbox created: sbx_abc123...
2
Installing Claude Code CLI...
3
✓ Claude Code CLI installed
4
Installing Anthropic SDK...
5
✓ Anthropic SDK installed
6
Verifying SDK connection...
7
SDK imported successfully
8
Anthropic SDK version: 1.2.3
9
SDK is ready to use
10
✓ Anthropic SDK is properly connected
11

12
Success! Both Claude Code CLI and Anthropic SDK are installed and ready to use.
13
Sandbox stopped

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.

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

1
try {
2
  // Your sandbox operations
3
} finally {
4
  await sandbox.stop();
5
  console.log('Sandbox stopped');
6
}

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

1
const sandbox = await Sandbox.create({
2
  timeout: ms('10m'), // 10 minutes for installation
3
  // Maximum: 5 hours for Pro/Enterprise, 45 minutes for Hobby
4
});
5

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

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.

• Vercel Sandbox documentation
• Vercel Sandbox reference documentation for advanced configuration
• Hosting Claude Agent Guide
• Claude Agent SDK documentation to learn about building AI agents