Claude Agent SDK with Vercel Sandbox Backing

Run the Claude CLI in Vercel's serverless environment using Vercel Sandbox microVMs.

Problem

The Claude Agent SDK works locally but fails on Vercel deployment:

Error: Claude Code executable not found

Vercel's serverless functions don't have the Claude CLI installed.

Solution

This SDK runs the Claude CLI inside Vercel Sandbox microVMs, enabling Claude Agent functionality in serverless environments.

[Your API Route] → [This SDK] → [Vercel Sandbox] → [Claude CLI] → [Anthropic API]

Installation

npm install @bugzy-ai/sandbox-agent-sdk

Quick Start

import { query } from '@bugzy-ai/sandbox-agent-sdk';

const result = await query({
  prompt: 'What is the capital of France?',
});

console.log(result.text); // "The capital of France is Paris."

Features

• ✅ Drop-in replacement for local Claude CLI usage
• ✅ Streaming support with SSE for real-time responses
• ✅ Multi-turn conversations with session management
• ✅ Custom tools via MCP (Model Context Protocol)
• ✅ Snapshots for faster cold starts
• ✅ VFS for mounting GitHub repos or custom files

API

Simple Query

import { query } from '@bugzy-ai/sandbox-agent-sdk';

// Get just the text response
const q = query({ prompt: 'Hello!' });
const text = await q.text();
console.log(text);

Streaming

import { query, isAssistantMessage, extractText } from '@bugzy-ai/sandbox-agent-sdk';

for await (const message of query({ prompt: 'Tell me a story' })) {
  if (isAssistantMessage(message)) {
    process.stdout.write(extractText(message));
  }
}

Multi-turn Conversations

import { VercelClaudeClient } from '@bugzy-ai/sandbox-agent-sdk';

const client = new VercelClaudeClient({
  systemPrompt: 'You are a helpful assistant.',
});

await client.connect();

const response1 = await client.chat('My name is Alice.');
const response2 = await client.chat('What is my name?');
// Claude remembers the conversation context

await client.disconnect();

Custom Tools

import { tool, createSdkMcpServer } from '@bugzy-ai/sandbox-agent-sdk';
import { z } from 'zod';

const weatherTool = tool(
  'get_weather',
  'Get the current weather for a location',
  { location: z.string() },
  async ({ location }) => {
    const weather = await fetchWeather(location);
    return { content: [{ type: 'text', text: weather }] };
  }
);

const server = createSdkMcpServer({
  name: 'my-tools',
  tools: [weatherTool],
});

Snapshots (Faster Cold Starts)

import { createSnapshot, query } from '@bugzy-ai/sandbox-agent-sdk';

// Create once (during deployment)
const snapshotId = await createSnapshot({ name: 'claude-ready' });

// Use for all queries
const result = await query({
  prompt: 'Hello!',
  snapshotId,
});

Next.js API Route Example

// app/api/chat/route.ts
import { NextRequest } from 'next/server';
import { query, isAssistantMessage, extractText } from '@bugzy-ai/sandbox-agent-sdk';

export const runtime = 'nodejs';
export const maxDuration = 300;

export async function POST(request: NextRequest) {
  const { prompt } = await request.json();

  const stream = new ReadableStream({
    async start(controller) {
      for await (const msg of query({ prompt })) {
        if (isAssistantMessage(msg)) {
          controller.enqueue(new TextEncoder().encode(extractText(msg)));
        }
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { 'Content-Type': 'text/plain' },
  });
}

Environment Variables

# Required
ANTHROPIC_API_KEY=sk-ant-xxx

# Optional (for faster cold starts)
CLAUDE_SANDBOX_SNAPSHOT_ID=snap_xxx

# Optional (for team deployments)
VERCEL_TEAM_ID=team_xxx

Documentation

• Setup Guide - Detailed setup instructions
• Examples - Working code examples

Examples

• basic-query - Simple query example
• streaming-api - Next.js API with SSE
• custom-tools - Database query tools

Architecture

| Component | Location | Purpose | |-----------|----------|---------| | Your API Route | Vercel Functions | Entry point, handles requests | | This SDK | Vercel Functions | Manages sandbox lifecycle | | Vercel Sandbox | MicroVM | Runs Claude CLI in isolated environment | | Claude CLI | Inside Sandbox | Communicates with Anthropic API | | Custom Tools | Your Functions | Access databases, APIs (secure) |

Performance

| Scenario | Cold Start | Warm | |----------|------------|------| | Fresh sandbox | ~45s | - | | With snapshot | ~3-5s | ~1s |

Recommendation: Always use snapshots in production.

Security

• Anthropic API key is passed to sandbox but never logged
• Custom tools run in your application, not the sandbox
• Each sandbox is an isolated microVM
• Database credentials stay in your application

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines first.