---
title: How to use Vercel Drives with an eve agent
description: Mount Vercel Drives in an eve agent's sandbox to give each user a persistent workspace and share read-only reference data across sessions.
url: "https://vercel.com/kb/guide/vercel-drives-eve-agent"
published: 2026-10-13
last_updated: 2026-10-13
authors: Ben Sabic
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

Vercel Drives give an eve agent's sandbox persistent storage that outlives any single session. Files the agent writes to a mounted drive stay on the drive after the sandbox stops, ready for the next session to pick up where the last one left off.

Use drives for agent workspaces that build up over time, dependency caches, and reference datasets that every session reads. You configure drives in the agent's sandbox file by passing `mounts` to the Vercel Sandbox environment's `open()` method, and the agent reads and writes the mounted directory with its built-in sandbox tools. For a complete working agent, see the [eve Vercel Drives starter](https://vercel.com/templates/eve/eve-vercel-drives-starter).

## Overview

In this guide, you'll learn how to:

- Decide when to use a drive and when to use an eve memory provider
  
- Give each user a persistent workspace drive
  
- Share a read-only reference drive across every session
  
- Keep the drive, sandbox snapshot, and each session in the same region
  
- Manage drive lifecycle and troubleshoot common mount errors
  

## Prerequisites

Before you begin, make sure you have:

- A [Vercel account](https://vercel.com/signup).
  
- Your own eve project. If you don't have one yet, create it with `npx eve init my-agent` or follow the [first agent tutorial](https://eve.dev/docs/tutorial/first-agent).
  
- Vercel Sandbox as the agent's sandbox provider. Drives mount only into Vercel Sandboxes, through `VercelSandbox` from `eve/sandbox/vercel`.
  

For local development, you also need Node.js 24+ and the [Vercel CLI](https://vercel.com/docs/cli).

## How Vercel Drives work with eve

Every eve session gets its own sandbox rooted at `/workspace`. With `VercelSandbox`, that sandbox is a persistent Vercel Sandbox that eve creates the first time the session uses it. eve passes your `mounts` when it creates the session's sandbox, and the mounts stay part of that sandbox's configuration, so the sandbox mounts the drive again each time eve resumes it.

The drive itself lives outside any sandbox and detaches with its contents intact when the sandbox stops, which lets a new session's sandbox mount it and see every file earlier sessions wrote.

Drives and eve memory providers both persist data across sessions, but the model reaches them differently:

- **Memory providers**: eve adds recalled memory to the model’s context before each turn. Use memory for facts and preferences the model should always see.
  
- **Drives**: Files on a drive enter the model’s context only when the agent opens them with `bash`, `read_file`, or another sandbox tool. Use a drive for project files, datasets, generated artifacts, and caches.
  

Many agents use both. If you’re adding memory alongside a drive, [the eve memory provider guide](https://vercel.com/kb/guide/choose-an-eve-memory-provider) compares the available options.

Vercel Drives have constraints that shape how an eve agent should use them:

| Constraint                                        | What it means for an eve agent                                                                |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| One read-write mount at a time                    | Only one session's running sandbox can write to a given drive.                                |
| Unlimited read-only snapshot mounts               | Any number of sessions can read a drive concurrently through a snapshot mount.                |
| Single region per drive                           | The sandbox's main region must match the drive's region.                                      |
| Up to four drives per sandbox                     | Each drive needs its own absolute mount path, and mount paths can't overlap.                  |
| 1 TiB default size (1 GiB on Hobby), 16 TiB quota | Set `maxSize` in bytes when you create the drive to change the limit.                         |
| Names unique per Vercel project                   | Drive names can be up to 64 characters, using only letters, digits, hyphens, and underscores. |

Mount drives outside `/workspace`, at paths such as `/data` or `/reference`. eve owns `/workspace` and seeds it from `agent/sandbox/workspace/`, so a separate path keeps session files and drive files apart.

## Steps

### 1\. Link your eve project to Vercel

When your agent runs on Vercel, the Vercel Sandbox SDK authenticates automatically with your project’s OIDC token. For local development, link your eve project and download a development token:

```bash
vercel link
vercel env pull
```

`vercel link` connects the directory to your Vercel project, and `vercel env pull` writes `VERCEL_OIDC_TOKEN` and other development variables to your environment file.

The OIDC token expires after 12 hours, so run `vercel env pull` again if drive or sandbox calls start failing with authentication errors.

### 2\. Choose one region for the drive and the sandbox

Vercel creates drives in `iad1` by default, and every sandbox that mounts a drive must run in the drive's region. The project's default sandbox region doesn't apply to sandboxes that mount drives, so set the region explicitly.

During `eve build`, eve also prepares a sandbox snapshot from the environment and creates each session's sandbox from it, and that snapshot must exist in the session's region. Passing `region` to `VercelSandbox.environment()` keeps the prepared snapshot and every session sandbox in the same region as the drive:

```typescript
import { defineSandbox } from "eve/sandbox";
import { VercelSandbox } from "eve/sandbox/vercel";

const REGION = "iad1";

export const environment = VercelSandbox.environment({ region: REGION });

export default defineSandbox(() => environment.open());
```

Pass the same `REGION` value to every `Drive.getOrCreate()` call in your project.

To use another region, pick one from the [Vercel Sandbox regions](https://vercel.com/docs/sandbox/concepts/regions) list before creating any drives, because a drive's region can't change after creation.

### 3\. Mount a persistent workspace drive for each user

Give each authenticated user their own read-write drive so files persist across that user's sessions without other users seeing them. eve's sandbox selector receives the session's authentication, and `Drive` is re-exported from `eve/sandbox/vercel`:

```typescript
import { createHash } from "node:crypto";
import { defineSandbox } from "eve/sandbox";
import { Drive, VercelSandbox } from "eve/sandbox/vercel";

const REGION = "iad1";

export const environment = VercelSandbox.environment({ region: REGION });

export default defineSandbox(async ({ session }) => {
  const owner = session.auth.initiator;

  if (owner === null || owner.principalType === "anonymous" || owner.principalType === "runtime") {
    return environment.open();
  }

  const ownerKey = JSON.stringify([
    owner.principalType,
    owner.authenticator,
    owner.issuer ?? null,
    owner.principalId,
  ]);
  const digest = createHash("sha256").update(ownerKey).digest("hex").slice(0, 32);

  const workspace = await Drive.getOrCreate({
    name: `workspace-${digest}`,
    region: REGION,
  });

  return environment.open({ mounts: { "/data": workspace } });
});
```

The selector ties the drive to `session.auth.initiator`, the caller who started the session, so the drive stays with the session’s owner even if someone else sends a later message. If other people can join a session, enforce ownership at the channel boundary, because the agent reads `/data` for anyone it answers.

Hashing the principal turns any ID, including emails and URLs, into a valid drive name and keeps raw user identifiers out of the drive list. Including the principal type, authenticator, and issuer in the hash keeps two users with the same ID in different authentication systems apart. For multi-tenant applications, add the tenant ID to the hash, as the [Multi-tenant memory](https://eve.dev/docs/patterns/multi-tenant-memory) pattern does for memory scope.

`Drive.getOrCreate()` returns the existing drive when one with that name already exists, or creates it otherwise. After the selector succeeds, eve checkpoints the sandbox, and later turns and process restarts resume it without calling `Drive.getOrCreate()` again. Anonymous and runtime sessions don’t get a drive.

While running eve through the terminal UI, every local session shares the `local-dev` principal and mounts the same workspace drive.

### 4\. Tell the agent where its persistent files live

The model doesn't know a drive exists until you describe it. Add the mount paths and their purpose to `agent/instructions.md`:

```markdown
Files under /data persist across sessions for the current user. Keep project
files, notes, and work in progress there. Files elsewhere in /workspace belong
to this session only and are not available in later sessions.
```

Drive contents are user-controlled data that can contain instructions aimed at the model. If the agent doesn't need outbound network access, pass `networkPolicy: "deny-all"` to `environment.open()`, as the [eve Vercel Drives starter](https://github.com/vercel-labs/eve-vercel-drives-starter/blob/main/agent/sandbox.ts) does, so injected instructions can't send file contents outside the sandbox.

### 5\. Share a read-only reference drive across sessions

Mount a read-only snapshot of a drive when every session needs the same data, such as documentation. Snapshot mounts don't count against the single read-write mount, which lets any number of eve sessions mount one concurrently.

Seed the drive before any session mounts it, because mounting a snapshot of a drive that has never been written to fails with a `drive_not_initialized` error.

Install the Vercel Sandbox SDK in your project:

**pnpm**

```bash
pnpm i @vercel/sandbox
```

**npm**

```bash
npm i @vercel/sandbox
```

**yarn**

```bash
yarn add @vercel/sandbox
```

**bun**

```bash
bun add @vercel/sandbox
```

Then create a one-off script that seeds the drive with your data:

```typescript
import { Drive, Sandbox } from "@vercel/sandbox";

const REGION = "iad1";

const reference = await Drive.getOrCreate({ name: "reference-data", region: REGION });

const sandbox = await Sandbox.create({
  region: REGION,
  mounts: { "/reference": reference },
  persistent: false,
  timeout: 10 * 60 * 1000,
});

try {
  const result = await sandbox.runCommand("sh", [
    "-c",
    "curl -fsSL https://example.com/your-dataset.tar.gz | tar -xz -C /reference",
  ]);

  if (result.exitCode !== 0) {
    throw new Error(await result.stderr());
  }
} finally {
  await sandbox.stop();
}
```

Setting `persistent: false` stops the SDK from keeping the seeding sandbox around after it stops, and the `finally` block stops the sandbox even when the command fails, which releases the read-write mount right away. Replace the URL with the location of your data, then run the script with the token from `.env.local`:

```bash
npx tsx --env-file=.env.local scripts/seed-reference-drive.mts
```

To seed the drive from a local folder instead, adapt the script accordingly.

Next, mount a snapshot of the reference drive alongside each user's workspace drive. Snapshot mounts can reference the drive by name, so the selector doesn't need to look up the reference drive in every session:

```typescript
import { createHash } from "node:crypto";
import { defineSandbox } from "eve/sandbox";
import { Drive, VercelSandbox } from "eve/sandbox/vercel";

const REGION = "iad1";
const reference = { drive: "reference-data", mode: "snapshot" } as const;

export const environment = VercelSandbox.environment({ region: REGION });

export default defineSandbox(async ({ session }) => {
  const owner = session.auth.initiator;

  if (owner === null || owner.principalType === "anonymous" || owner.principalType === "runtime") {
    return environment.open({ mounts: { "/reference": reference } });
  }

  const ownerKey = JSON.stringify([
    owner.principalType,
    owner.authenticator,
    owner.issuer ?? null,
    owner.principalId,
  ]);
  const digest = createHash("sha256").update(ownerKey).digest("hex").slice(0, 32);

  const workspace = await Drive.getOrCreate({
    name: `workspace-${digest}`,
    region: REGION,
  });

  return environment.open({
    mounts: {
      "/data": workspace,
      "/reference": reference,
    },
  });
});
```

Each snapshot reflects the drive at the moment it's mounted. Rerun the seed script to update the reference data, and sessions whose sandboxes eve creates after the update mount the new version.

Describe the reference path in `agent/instructions.md` too, for example: "Files under /reference are read-only reference material shared by every user."

### 6\. Test the drives locally

Start the agent’s local development server:

```bash
eve dev
```

The first sandbox access in `eve dev` prepares the sandbox environment, so the first tool call that uses the sandbox takes longer than later ones. Ask the agent to write a short note to `/data/notes.md`, then start a new session and ask it to read the note back. If the note appears, the workspace drive persisted across sessions. Ask the agent to list `/reference` to confirm the snapshot mount.

To see which sandbox each drive is attached to, run `sandbox drives ls` with the [Sandbox CLI](https://vercel.com/docs/sandbox/cli-reference). Detached drives show no current sandbox.

## Manage drive lifecycle

Vercel Drives persist until you delete them. Vercel bills each drive for the storage it uses rather than its maximum size, plus the data sandboxes read and write, at the rates listed in [Sandbox pricing](https://vercel.com/docs/sandbox/pricing#drive-storage). Neither eve nor Vercel deletes a user's workspace drive when the user leaves, so delete it as part of your account deletion flow:

```typescript
import { Drive } from "@vercel/sandbox";

export async function deleteUserWorkspace(driveName: string, region: string) {
  const drive = await Drive.getOrCreate({ name: driveName, region });
  await drive.delete();
}
```

Compute `driveName` with the same hash the sandbox file uses. Stop or delete the user's active sessions first, because Vercel can't delete a drive while it's attached to a running sandbox.

## Troubleshooting

### Sandbox creation fails with `drive_region_mismatch`

The session's sandbox is running in a different region from the drive. Set the same `region` on `VercelSandbox.environment()` and on every `Drive.getOrCreate()` call.

### Sandbox creation fails with `snapshot_region_mismatch`

eve prepared the agent's sandbox snapshot in a different region from the one the session sandbox runs in. This happens when you add `region` to `VercelSandbox.environment()` after a build, or when the environment has no `region` and the project default differs from the drive's region.

Set `region` on the environment, then rebuild or redeploy so eve prepares a new snapshot in that region. Changing environment options creates a new environment generation, which new sessions use.

### Another session can't mount the user's workspace drive

Only one sandbox at a time can mount a drive read-write. If a user has two sessions running at once, the second session's sandbox can't mount the workspace drive until the first session's sandbox stops and the drive detaches. eve retries the sandbox selector on the next sandbox access.

If your users regularly run concurrent sessions, mount the workspace as a snapshot in every session and write to it through a tool instead. The [eve Vercel Drives starter](https://github.com/vercel-labs/eve-vercel-drives-starter/blob/main/agent/tools/save_to_drive.ts)'s `save_to_drive` tool does this by starting a short-lived sandbox that holds the read-write mount only while it writes, and reporting `drive_busy` when another write is in progress.

### Mounting the reference drive fails with `drive_not_initialized`

The reference drive has never been written to. Run the seed script from [step five](#5.-share-a-read-only-reference-drive-across-sessions) before starting sessions that mount the reference snapshot.

To keep the agent working while the drive is empty, wrap `environment.open()` in `try/catch` and open an unmounted sandbox on failure, as the starter does. eve doesn't rerun a selector after it succeeds, so a session that falls back keeps running without the mount, and only new sessions pick up the drive.

## Next steps

- Deploy the [eve Vercel Drives starter](https://vercel.com/templates/eve/eve-vercel-drives-starter) for a complete agent that reads and saves files on a Vercel Drive.
  
- Choose a memory provider for facts the model should always see in [How to choose an eve memory provider](https://vercel.com/kb/guide/choose-an-eve-memory-provider).
  
- Back memory with your own storage in [How to build a custom eve memory provider](https://vercel.com/kb/guide/build-a-custom-eve-memory-provider).
  
- Learn the full Drive API in the [Drives documentation](https://vercel.com/docs/sandbox/concepts/drives).

## More eve guides

- [How to build a custom eve memory provider](/kb/guide/build-a-custom-eve-memory-provider): Implement the eve memory provider contract with defineMemoryProvider() to back an eve memory slot with your own database, vector index, or memory service.
- [How to choose an eve memory provider](/kb/guide/choose-an-eve-memory-provider): Compare File memory, Supermemory, Upstash AgentKit, and Kybernesis Arcana by recall, capture, and storage to choose an eve memory provider for your agent.
- [Build a software factory with eve](/kb/guide/eve-software-factory): Foreman, a software factory built on eve. It turns GitHub and Linear work items into reviewed draft pull requests through four agent stations, triaging issues and fixing its own red CI along the way.