Vercel Sandbox

[ngoiyaeric]

Yes. If you're using the Vercel AI SDK ecosystem, there are now a few options for code generation and execution sandboxes:

1. AI SDK Playground

The official AI SDK site includes a playground for experimenting with prompts, tool calls, structured outputs, agents, and UI generation. ([AI SDK][1])

[AI SDK Playground](https://ai-sdk.dev?utm_source=chatgpt.com)

---

2. Vercel Sandbox (Recommended for Codegen Agents)

Vercel released a dedicated sandbox environment designed specifically for AI-generated code and coding agents. It provides:

• Isolated execution environments
• File system access
• Command execution
• Live previews
• Support for generated applications
• TypeScript and Python runtimes
• Integration with AI SDK agents

This is the same infrastructure used for AI coding workflows and agent execution. ([Vercel][2])

[Vercel Sandbox Docs](https://vercel.com/docs/vercel-sandbox?utm_source=chatgpt.com)

Example:

import { Sandbox } from "@vercel/sandbox";

const sandbox = await Sandbox.create();

await sandbox.runCommand("npm create vite@latest app");

---

3. AI SDK + Sandbox Agent Pattern

Vercel has an official guide showing how to:

1. Generate code with an LLM.
2. Write files into a sandbox.
3. Run the code.
4. Stream logs back to the user.
5. Return a preview URL.

This is effectively the architecture behind products like v0 and many coding agents. ([Vercel][3])

[Run AI Generated Code Safely Guide](https://vercel.com/guides/running-ai-generated-code-sandbox?utm_source=chatgpt.com)

---

4. If You're Building a Cursor / Claude Code Competitor

A common architecture is:

User
  ↓
AI SDK Agent
  ↓
Planner
  ↓
Vercel Sandbox
  ↓
Filesystem
  ↓
npm/pnpm
  ↓
Preview Server
  ↓
Live URL

Use HTML styled report generation instead of template hardcoded ones.

[ngoiyaeric]

@coderabbitai plan

[coderabbitai]

Coding Plan

Summary

• Follow the established tool factory pattern (ToolProps → { description, parameters, execute }) to create a new sandboxTool that integrates naturally with the researcher agent
• Use Vercel Sandbox's microVM isolation for secure code execution with writeFiles(), runCommand(), and domain() for preview URLs
• Stream execution logs to the UI in real-time using createStreamableValue and uiStream.append(), matching existing tool UX patterns
• Display results via a new SandboxSection component containing a terminal-style log viewer and sandboxed iframe for live previews

Design Choices

Design Choice 1: What execution model should the sandbox tool use?

Options Considered:

1. Explicit sandbox tool that the LLM invokes when it decides code execution is needed
2. Automatic code extraction and execution whenever the LLM generates code blocks

Chosen Option: 1

Rationale: An explicit tool gives the LLM control over when to execute code, follows established tool patterns in the codebase, and provides clearer boundaries for what gets executed.

Design Choice 2: Which runtime environments to support initially?

Options Considered:

1. Support all available runtimes from the start
2. Start with Node.js only, extend to other runtimes later

Chosen Option: 2

Rationale: Starting with Node.js keeps the initial scope manageable while proving the architecture. The tool schema can be extended to support additional runtimes in a follow-up.

Design Choice 3: How should HTML report generation work?

Options Considered:

1. LLM generates complete HTML/CSS/JS code that executes in the sandbox and serves via preview URL
2. LLM generates structured data that gets rendered by predefined React templates

Chosen Option: 1

Rationale: True code generation where the LLM writes HTML/CSS/JS files to the sandbox, runs a simple HTTP server, and the result is displayed via iframe. This matches the ticket's emphasis on dynamic generation over templates.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Infrastructure & Configuration

Set up the Vercel Sandbox package, authentication configuration, schema definitions, and type system updates needed before implementing the tool itself.

Task 1: Install Vercel Sandbox Package

Add the @vercel/sandbox package to enable isolated code execution.

• Add @vercel/sandbox to dependencies in package.json
• Verify compatibility with existing AI SDK version (4.3.19)

Task 2: Configure Environment Variables

Set up authentication credentials required by Vercel Sandbox.

• Add VERCEL_TEAM_ID, VERCEL_PROJECT_ID, and VERCEL_TOKEN entries to .env.example with documentation comments
• The SDK uses these for OIDC-based authentication to provision microVMs

Task 3: Create Sandbox Tool Schema

Define the Zod schema for sandbox tool parameters following the pattern in lib/schema/.

• Create lib/schema/sandbox.ts with a schema defining: code (string, the code to execute), language (enum starting with 'javascript'/'typescript'), filename (string for the entry file), and optional dependencies (array of npm packages to install)
• Export the inferred TypeScript type alongside the schema
• Follow the documentation patterns used in searchSchema and retrieveSchema

Task 4: Update AIMessage Type Definitions

Extend the type system to support sandbox execution results in message history.

• Add 'sandbox_result' to the type union in AIMessage type in lib/types/index.ts
• Add a SandboxResult type defining the structure: logs (stdout/stderr array), exitCode, previewUrl (optional), error (optional)

🤖 Prompt for AI agents

This phase sets up all prerequisite infrastructure for the Vercel Sandbox
integration before any tool logic is written. The goal is to install the
package, configure credentials, define the Zod schema, and extend the type
system.

- Add `@vercel/sandbox` to `package.json` dependencies and verify compatibility
with AI SDK v4.3.19
- Add `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_TOKEN` to
`.env.example` with documentation comments explaining their use for OIDC-based
microVM authentication
- Create `lib/schema/sandbox.ts`:
- Define a Zod schema with fields: `code` (string), `language` (enum of
`'javascript'` and `'typescript'`), `filename` (string), and optional
`dependencies` (array of strings for npm packages)
  - Export the inferred TypeScript type alongside the schema
  - Follow the same documentation style as `searchSchema` and `retrieveSchema`
- In `lib/types/index.ts`:
  - Add `'sandbox_result'` to the `type` union in the `AIMessage` type
- Add a new `SandboxResult` type with fields: `logs` (stdout/stderr array),
`exitCode`, optional `previewUrl`, and optional `error`

Phase 2: Sandbox Tool Implementation

Build the sandbox tool following established patterns, implementing code writing, execution, log streaming, and preview URL generation.

Task 1: Create Sandbox Tool Factory

Implement the main sandbox tool following the factory pattern used by existing tools.

• Create lib/agents/tools/sandbox.tsx exporting a sandboxTool factory function that receives ToolProps
• Return an object with description (explain that this tool executes code in an isolated environment), parameters (the Zod schema from Task 1.3), and execute async function
• The execute function should: create a sandbox instance, write the code file, optionally install dependencies, run the code, collect output, and return structured results

Task 2: Implement Code Execution Logic

Build the core sandbox execution flow with file writing and command running.

• In the execute function, use Sandbox.create({ runtime: 'node24', ports: [3000], timeout: 60000 }) to provision the microVM
• Use sandbox.writeFiles() to write the user's code to the sandbox filesystem (e.g., /vercel/sandbox/app.js)
• If dependencies are specified, run sandbox.runCommand('npm install <packages>') first
• Run the main code with sandbox.runCommand('node app.js') or appropriate command based on language

Task 3: Implement Log Streaming to UI

Stream execution logs to the UI in real-time following the createStreamableValue pattern.

• Create a createStreamableValue<string> for logs at the start of execute()
• Immediately uiStream.append(<SandboxSection logs={streamableLogs.value} />) to show the UI
• Use for await (const log of command.logs()) to iterate over stdout/stderr entries
• Update the streamable value with each log entry, distinguishing stdout vs stderr
• Call streamableLogs.done() when execution completes

Task 4: Implement Preview URL Generation

Generate and return a publicly accessible preview URL for web-based outputs.

• For code that starts an HTTP server (detected by presence of http, express, serve, etc. in code), use detached: true in runCommand to keep the server running
• Call sandbox.domain(3000) to get the public preview URL
• Include the previewUrl in the tool's return value
• Handle cases where no server is started (just return logs and exit code)

Task 5: Implement Error Handling and Cleanup

Add robust error handling following patterns from existing tools.

• Wrap sandbox operations in try/catch blocks
• On error, update uiStream with an error card (following search.tsx pattern)
• Always call sandbox.stop() in a finally block for non-preview executions to clean up resources
• Return partial results with error information when failures occur

Task 6: Register Tool in Tool Registry

Add the sandbox tool to the tools registry used by the researcher agent.

• Import sandboxTool in lib/agents/tools/index.tsx
• Add sandbox: sandboxTool({ uiStream, fullResponse }) to the getTools() return object
• Make registration conditional on presence of Vercel auth environment variables (similar to how search is conditional on TAVILY_API_KEY)

🤖 Prompt for AI agents

This phase implements the full sandbox tool in `lib/agents/tools/sandbox.tsx`
following the existing factory pattern (`ToolProps` → `{ description,
parameters, execute }`). The goal is to wire up sandbox provisioning, file
writing, command execution, log streaming, preview URL generation, error
handling, and registry registration.

- Create `lib/agents/tools/sandbox.tsx` exporting a `sandboxTool` factory that
receives `ToolProps` and returns `{ description, parameters, execute }`:
- `description`: explain the tool executes code in an isolated microVM
environment
  - `parameters`: use the Zod schema defined in `lib/schema/sandbox.ts`
  - `execute`: async function implementing the full execution flow below

- **Core execution flow** in `execute()`:
- Provision microVM: `Sandbox.create({ runtime: 'node24', ports: [3000],
timeout: 60000 })`
- Write user code to filesystem using `sandbox.writeFiles()` (e.g.,
`/vercel/sandbox/app.js`)
- If `dependencies` are specified, run `sandbox.runCommand('npm install
<packages>')` before executing user code
- Run main code via `sandbox.runCommand('node app.js')` (or appropriate command
per language)

- **Log streaming**:
  - Create `createStreamableValue<string>` for logs at the top of `execute()`
- Immediately call `uiStream.append(<SandboxSection logs={streamableLogs.value}
/>)` to render UI
- Use `for await (const log of command.logs())` to stream stdout/stderr entries
  - Update the streamable value per entry, distinguishing stdout vs stderr
  - Call `streamableLogs.done()` after execution completes

- **Preview URL generation**:
- Detect HTTP server usage by checking for `http`, `express`, `serve`, etc. in
the code string
  - If detected, use `detached: true` in `runCommand` to keep the server alive
  - Call `sandbox.domain(3000)` to obtain the public preview URL
  - Include `previewUrl` in the return value; omit it when no server is started

- **Error handling and cleanup**:
  - Wrap all sandbox operations in try/catch
- On error, update `uiStream` with an error card following the `search.tsx`
pattern
- In a `finally` block, call `sandbox.stop()` for non-preview (non-detached)
executions
  - Return partial results including error information on failure

- **Registry registration** in `lib/agents/tools/index.tsx`:
  - Import `sandboxTool`
- Add `sandbox: sandboxTool({ uiStream, fullResponse })` to the `getTools()`
return object
- Guard the registration behind a check for the presence of Vercel auth
environment variables (same pattern as `TAVILY_API_KEY` guards `search`)

Phase 3: UI Components & Integration

Create the display components for sandbox results and wire up the message history rendering.

Task 1: Create SandboxSection Component

Build the main container component for displaying sandbox execution results.

• Create components/sandbox-section.tsx as the top-level result display
• Accept props: logs (StreamableValue<string>), previewUrl (optional string), exitCode (optional number), error (optional string)
• Use useStreamableValue from ai/rsc to subscribe to the streaming logs
• Render a collapsible <Section> with a terminal-style log viewer and optional preview iframe
• Style with appropriate icons (Terminal icon from lucide-react)

Task 2: Create Log Viewer Component

Build a component for displaying execution logs with stdout/stderr distinction.

• Create components/sandbox-logs.tsx with a scrollable container (overflow-auto max-h-[300px])
• Use monospace font (font-mono text-sm) for terminal-style display
• Parse log entries to distinguish stdout (default color) from stderr (red/error color)
• Auto-scroll to bottom as new logs stream in
• Show a loading indicator while execution is in progress

Task 3: Create Preview Iframe Component

Build a sandboxed iframe component for displaying live preview URLs.

• Create components/sandbox-preview.tsx rendering an <iframe> when previewUrl is provided
• Use sandbox="allow-scripts allow-same-origin" attribute for security
• Style with w-full aspect-video following the YouTube embed pattern
• Include a header showing the preview URL with an "Open in new tab" link
• Add loading state while the preview loads

Task 4: Update getUIStateFromAIState Mapping

Add the sandbox tool to the message history reconstruction logic.

• In app/actions.tsx, add a new case in getUIStateFromAIState() for name === 'sandbox' under the role: 'tool' branch
• Parse the tool output to extract logs, exitCode, previewUrl, and error
• Return the <SandboxSection> component with appropriate props
• Wrap in isCollapsed: true to match other tool result patterns

Task 5: Update Researcher System Prompt

Inform the LLM about the new sandbox tool capabilities.

• Update the system prompt in lib/agents/researcher.tsx to mention the sandbox tool
• Describe when to use it: executing code snippets, generating dynamic HTML reports, running data transformations
• Emphasize that this tool executes code in isolation and can produce live previews for web content

🤖 Prompt for AI agents

This phase creates all React UI components for displaying sandbox results and
wires them into the existing message history and researcher system prompt. The
goal is to render streaming logs, optional live previews, and ensure history
reconstruction works correctly.

- **`components/sandbox-section.tsx`** (top-level container):
- Accept props: `logs` (`StreamableValue<string>`), optional `previewUrl`
(string), optional `exitCode` (number), optional `error` (string)
  - Use `useStreamableValue` from `ai/rsc` to subscribe to streaming logs
- Render a collapsible `<Section>` containing `<SandboxLogs>` and, if
`previewUrl` is present, `<SandboxPreview>`
  - Use the Terminal icon from `lucide-react` for styling

- **`components/sandbox-logs.tsx`** (log viewer):
  - Scrollable container styled with `overflow-auto max-h-[300px]`
  - Monospace font: `font-mono text-sm`
- Parse log entries to distinguish stdout (default color) vs stderr (red/error
color)
  - Auto-scroll to bottom as new log entries stream in
  - Show a loading indicator while execution is in progress

- **`components/sandbox-preview.tsx`** (iframe preview):
  - Render an `<iframe>` only when `previewUrl` is provided
  - Set `sandbox="allow-scripts allow-same-origin"` for security
- Style with `w-full aspect-video` following the YouTube embed pattern in
`video-search-results.tsx`
  - Include a header with the preview URL and an "Open in new tab" link
  - Add a loading state while the iframe content loads

- **`app/actions.tsx`** — update `getUIStateFromAIState()`:
  - Under the `role: 'tool'` branch, add a case for `name === 'sandbox'`
- Parse the tool output to extract `logs`, `exitCode`, `previewUrl`, and `error`
  - Return `<SandboxSection>` with the extracted props
  - Set `isCollapsed: true` to match other tool result patterns

- **`lib/agents/researcher.tsx`** — update system prompt:
- Add a description of the sandbox tool: when to use it (executing code
snippets, generating dynamic HTML reports, running data transformations), and
that it executes code in isolation and can produce live previews for web content

Research

This is a Next.js 15 application using the Vercel AI SDK (v4.3.19) with React Server Components streaming (ai/rsc). The architecture follows a pipeline: submit() → taskManager → researcher (with tools) → querySuggestor. Tools are factory functions receiving ToolProps (uiStream, fullResponse, mapProvider) and returning { description, parameters, execute } objects. Each tool pushes UI components to uiStream via .append() / .update() and uses createStreamableValue for streaming data. The getUIStateFromAIState() function maps persisted message types to React components for chat history rendering. The only existing iframe pattern is YouTube embeds in video-search-results.tsx.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase sets up all prerequisite infrastructure for the Vercel Sandbox
integration before any tool logic is written. The goal is to install the
package, configure credentials, define the Zod schema, and extend the type
system.

- Add `@vercel/sandbox` to `package.json` dependencies and verify compatibility
with AI SDK v4.3.19
- Add `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_TOKEN` to
`.env.example` with documentation comments explaining their use for OIDC-based
microVM authentication
- Create `lib/schema/sandbox.ts`:
- Define a Zod schema with fields: `code` (string), `language` (enum of
`'javascript'` and `'typescript'`), `filename` (string), and optional
`dependencies` (array of strings for npm packages)
  - Export the inferred TypeScript type alongside the schema
  - Follow the same documentation style as `searchSchema` and `retrieveSchema`
- In `lib/types/index.ts`:
  - Add `'sandbox_result'` to the `type` union in the `AIMessage` type
- Add a new `SandboxResult` type with fields: `logs` (stdout/stderr array),
`exitCode`, optional `previewUrl`, and optional `error`
===============================================================================

Task: 2

This phase implements the full sandbox tool in `lib/agents/tools/sandbox.tsx`
following the existing factory pattern (`ToolProps` → `{ description,
parameters, execute }`). The goal is to wire up sandbox provisioning, file
writing, command execution, log streaming, preview URL generation, error
handling, and registry registration.

- Create `lib/agents/tools/sandbox.tsx` exporting a `sandboxTool` factory that
receives `ToolProps` and returns `{ description, parameters, execute }`:
- `description`: explain the tool executes code in an isolated microVM
environment
  - `parameters`: use the Zod schema defined in `lib/schema/sandbox.ts`
  - `execute`: async function implementing the full execution flow below

- **Core execution flow** in `execute()`:
- Provision microVM: `Sandbox.create({ runtime: 'node24', ports: [3000],
timeout: 60000 })`
- Write user code to filesystem using `sandbox.writeFiles()` (e.g.,
`/vercel/sandbox/app.js`)
- If `dependencies` are specified, run `sandbox.runCommand('npm install
<packages>')` before executing user code
- Run main code via `sandbox.runCommand('node app.js')` (or appropriate command
per language)

- **Log streaming**:
  - Create `createStreamableValue<string>` for logs at the top of `execute()`
- Immediately call `uiStream.append(<SandboxSection logs={streamableLogs.value}
/>)` to render UI
- Use `for await (const log of command.logs())` to stream stdout/stderr entries
  - Update the streamable value per entry, distinguishing stdout vs stderr
  - Call `streamableLogs.done()` after execution completes

- **Preview URL generation**:
- Detect HTTP server usage by checking for `http`, `express`, `serve`, etc. in
the code string
  - If detected, use `detached: true` in `runCommand` to keep the server alive
  - Call `sandbox.domain(3000)` to obtain the public preview URL
  - Include `previewUrl` in the return value; omit it when no server is started

- **Error handling and cleanup**:
  - Wrap all sandbox operations in try/catch
- On error, update `uiStream` with an error card following the `search.tsx`
pattern
- In a `finally` block, call `sandbox.stop()` for non-preview (non-detached)
executions
  - Return partial results including error information on failure

- **Registry registration** in `lib/agents/tools/index.tsx`:
  - Import `sandboxTool`
- Add `sandbox: sandboxTool({ uiStream, fullResponse })` to the `getTools()`
return object
- Guard the registration behind a check for the presence of Vercel auth
environment variables (same pattern as `TAVILY_API_KEY` guards `search`)
===============================================================================

Task: 3

This phase creates all React UI components for displaying sandbox results and
wires them into the existing message history and researcher system prompt. The
goal is to render streaming logs, optional live previews, and ensure history
reconstruction works correctly.

- **`components/sandbox-section.tsx`** (top-level container):
- Accept props: `logs` (`StreamableValue<string>`), optional `previewUrl`
(string), optional `exitCode` (number), optional `error` (string)
  - Use `useStreamableValue` from `ai/rsc` to subscribe to streaming logs
- Render a collapsible `<Section>` containing `<SandboxLogs>` and, if
`previewUrl` is present, `<SandboxPreview>`
  - Use the Terminal icon from `lucide-react` for styling

- **`components/sandbox-logs.tsx`** (log viewer):
  - Scrollable container styled with `overflow-auto max-h-[300px]`
  - Monospace font: `font-mono text-sm`
- Parse log entries to distinguish stdout (default color) vs stderr (red/error
color)
  - Auto-scroll to bottom as new log entries stream in
  - Show a loading indicator while execution is in progress

- **`components/sandbox-preview.tsx`** (iframe preview):
  - Render an `<iframe>` only when `previewUrl` is provided
  - Set `sandbox="allow-scripts allow-same-origin"` for security
- Style with `w-full aspect-video` following the YouTube embed pattern in
`video-search-results.tsx`
  - Include a header with the preview URL and an "Open in new tab" link
  - Add a loading state while the iframe content loads

- **`app/actions.tsx`** — update `getUIStateFromAIState()`:
  - Under the `role: 'tool'` branch, add a case for `name === 'sandbox'`
- Parse the tool output to extract `logs`, `exitCode`, `previewUrl`, and `error`
  - Return `<SandboxSection>` with the extracted props
  - Set `isCollapsed: true` to match other tool result patterns

- **`lib/agents/researcher.tsx`** — update system prompt:
- Add a description of the sandbox tool: when to use it (executing code
snippets, generating dynamic HTML reports, running data transformations), and
that it executes code in isolation and can produce live previews for web content

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!