# VercelSandbox

Executes commands as [Vercel](https://vercel.com) serverless functions. Provides globally-distributed, zero-infrastructure execution with automatic scaling.

> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).

> **Warning:** VercelSandbox is stateless. There is no persistent filesystem, no interactive shell, and no support for long-running or background processes. Only `/tmp` is writable and is ephemeral between invocations.

## Installation

**npm**:

```bash
npm install @mastra/vercel
```

**pnpm**:

```bash
pnpm add @mastra/vercel
```

**Yarn**:

```bash
yarn add @mastra/vercel
```

**Bun**:

```bash
bun add @mastra/vercel
```

## Usage

Add a `VercelSandbox` to a workspace and assign it to an agent:

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { VercelSandbox } from '@mastra/vercel'

const workspace = new Workspace({
  sandbox: new VercelSandbox({
    token: process.env.VERCEL_TOKEN,
  }),
})

const agent = new Agent({
  name: 'dev-agent',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})
```

### Team-scoped deployment with custom resources

```typescript
const workspace = new Workspace({
  sandbox: new VercelSandbox({
    token: process.env.VERCEL_TOKEN,
    teamId: 'team_abc123',
    regions: ['iad1', 'sfo1'],
    maxDuration: 120,
    memory: 3008,
    env: {
      NODE_ENV: 'production',
    },
  }),
})
```

## Constructor parameters

**token** (`string`): Vercel API token. Falls back to \`VERCEL\_TOKEN\` environment variable.

**teamId** (`string`): Vercel team ID for team-scoped deployments.

**projectName** (`string`): Existing Vercel project name. Auto-generated if omitted.

**regions** (`string[]`): Deployment regions. (Default: `['iad1']`)

**maxDuration** (`number`): Function maximum duration in seconds. (Default: `60`)

**memory** (`number`): Function memory in MB. (Default: `1024`)

**env** (`Record<string, string>`): Environment variables baked into the deployed function source. These are embedded at deploy time, not set dynamically.

**commandTimeout** (`number`): Per-invocation command timeout in milliseconds. (Default: `55000`)

**instructions** (`string | ((opts) => string)`): Custom instructions that override the default instructions returned by \`getInstructions()\`. Pass a string to fully replace, or a function to extend the defaults.

## Properties

**id** (`string`): Unique identifier for this sandbox instance.

**name** (`'VercelSandbox'`): Human-readable name.

**provider** (`'vercel'`): Provider type identifier.

**status** (`ProviderStatus`): Current lifecycle status: \`'pending'\`, \`'starting'\`, \`'running'\`, \`'stopping'\`, \`'stopped'\`, \`'destroying'\`, \`'destroyed'\`, or \`'error'\`.

## Limitations

VercelSandbox uses serverless functions under the hood, which means:

- **No persistent filesystem**: Files written to `/tmp` are ephemeral and cleared between invocations.
- **No interactive shell**: Commands run via `/bin/sh -c` with no stdin streaming.
- **No background processes**: No process manager, PIDs, or long-running tasks.
- **No mounting**: Cloud storage mounting (S3, GCS) is not supported.
- **Timeout limits**: Maximum execution time is bounded by `maxDuration` (default 60s).

## Related

- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
- [Workspace class](https://mastra.ai/reference/workspace/workspace-class)
- [E2BSandbox](https://mastra.ai/reference/workspace/e2b-sandbox) — full-featured cloud sandbox with persistent filesystem and process management