Volumes

Persistent storage that exists independently of sandbox lifecycles. Mount one volume across many sandboxes or read and write directly through the SDK.

Volumes are currently in private beta. If you’d like access, please reach out to us at [e-mail].

Volumes provide persistent storage that exists independently of sandbox lifecycles. Data written to a volume persists even after a sandbox is shut down, and the same volume can be mounted to multiple sandboxes — either at the same time for shared state across parallel agents, or sequentially to resume work in a new sandbox. You can also read and write to a volume directly through the SDK without mounting it to any sandbox.

One volume shared across multiple sandboxes

Each sandbox with its own volume

Standalone usage via SDK

When a volume is mounted to a sandbox, files can be read and written directly at the mount path using the regular sandbox filesystem API. The Volume SDK methods covered below are meant for working with a volume when it is not mounted to any sandbox.

Quickstart

Create a volume and mount it to a sandbox. Any file written under the mount path is persisted in the volume and remains available to future sandboxes.

JavaScript & TypeScript

import { Volume, Sandbox } from 'e2b'

const volume = await Volume.create('my-volume')

const sandbox = await Sandbox.create({
  volumeMounts: {
    '/mnt/my-data': volume,
  },
})

Managing volumes

The Volume class exposes lifecycle operations for creating, listing, inspecting, and destroying volumes.

Create a volume

Create a new named volume. Volume names can only contain letters, numbers, and hyphens.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')
console.log(volume.volumeId) // Volume ID
console.log(volume.name)     // 'my-volume'

Connect to an existing volume

Use connect() to get a handle to an existing volume by its ID. This is how you reach a volume that was created in a previous session.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.connect('volume-id')
console.log(volume.volumeId) // Volume ID
console.log(volume.name)     // Volume name

List volumes

List all volumes in your team.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volumes = await Volume.list()
console.log(volumes)
// [{ volumeId: '...', name: 'my-volume' }, ...]

Get volume info

Fetch metadata for a single volume by ID.

JavaScript & TypeScript

import { Volume } from 'e2b'

const info = await Volume.getInfo('volume-id')
console.log(info)
// { volumeId: '...', name: 'my-volume' }

Destroy a volume

Permanently delete a volume and all of its contents. This cannot be undone.

JavaScript & TypeScript

import { Volume } from 'e2b'

const success = await Volume.destroy('volume-id')
console.log(success) // true

Mounting volumes to a sandbox

Pass volumeMounts / volume_mounts to Sandbox.create() to attach one or more volumes when the sandbox starts. Keys are the mount paths inside the sandbox; values are either a Volume object or the volume name.

JavaScript & TypeScript

import { Volume, Sandbox } from 'e2b'

const volume = await Volume.create('my-volume')

// You can pass a Volume object
const sandbox = await Sandbox.create({
  volumeMounts: {
    '/mnt/my-data': volume,
  },
})

// Or pass the volume name directly
const sandbox = await Sandbox.create({
  volumeMounts: {
    '/mnt/my-data': 'my-volume',
  },
})

// Files written to /mnt/my-data inside the sandbox are persisted in the volume
await sandbox.files.write('/mnt/my-data/hello.txt', 'Hello, world!')

Reading and writing files

When a volume is not mounted, you can interact with its contents directly through the Volume instance methods.

Read a file

Read the contents of a file from a volume.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

const content = await volume.readFile('/path/to/file')
console.log(content)

Write a file

Write content to a file in the volume. Parent directories must already exist — use makeDir() / make_dir() if they don’t.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

await volume.writeFile('/path/to/file', 'file content')

Create a directory

Create a directory in the volume. Pass force: true / force=True to create any missing parent directories.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

await volume.makeDir('/path/to/dir')

// Create nested directories with force option
await volume.makeDir('/path/to/nested/dir', { force: true })

List directory contents

List the entries (files and subdirectories) at a path in the volume.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

const entries = await volume.list('/path/to/dir')
console.log(entries)
// [
//   { name: 'file.txt', type: 'file', path: '/path/to/dir/file.txt', size: 13, ... },
//   { name: 'subdir', type: 'directory', path: '/path/to/dir/subdir', size: 0, ... },
// ]

Remove files or directories

Remove a file, or remove a directory by passing the recursive option.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

// Remove a file
await volume.remove('/path/to/file')

// Remove a directory recursively
await volume.remove('/path/to/dir', { recursive: true })

File and directory metadata

Inspect files and directories with getInfo() / get_info(), check for existence with exists(), or change ownership and permissions with updateMetadata() / update_metadata().

Get information about a file

Retrieve metadata such as size, mode, owner, and timestamps for a file.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

// Create a new file
await volume.writeFile('/test_file.txt', 'Hello, world!')

// Get information about the file
const info = await volume.getInfo('/test_file.txt')

console.log(info)
// {
//   name: 'test_file.txt',
//   type: 'file',
//   path: '/test_file.txt',
//   size: 13,
//   mode: 0o644,
//   uid: 0,
//   gid: 0,
//   atime: 2025-05-26T12:00:00.000Z,
//   mtime: 2025-05-26T12:00:00.000Z,
//   ctime: 2025-05-26T12:00:00.000Z,
// }

Get information about a directory

The same getInfo() / get_info() method also works for directories.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

// Create a new directory
await volume.makeDir('/test_dir')

// Get information about the directory
const info = await volume.getInfo('/test_dir')

console.log(info)
// {
//   name: 'test_dir',
//   type: 'directory',
//   path: '/test_dir',
//   size: 0,
//   mode: 0o755,
//   uid: 0,
//   gid: 0,
//   atime: 2025-05-26T12:00:00.000Z,
//   mtime: 2025-05-26T12:00:00.000Z,
//   ctime: 2025-05-26T12:00:00.000Z,
// }

Check if a path exists

Use exists() to test whether a file or directory is present without throwing if it isn’t.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

const fileExists = await volume.exists('/test_file.txt')
console.log(fileExists) // true or false

Update metadata

Change a file or directory’s user ID, group ID, or permission mode.

JavaScript & TypeScript

import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

await volume.writeFile('/test_file.txt', 'Hello, world!')

const updated = await volume.updateMetadata('/test_file.txt', { uid: 1000, gid: 1000, mode: 0o600 })

console.log(updated)
// {
//   name: 'test_file.txt',
//   type: 'file',
//   path: '/test_file.txt',
//   size: 13,
//   mode: 0o600,
//   uid: 1000,
//   gid: 1000,
//   ...
// }

Uploading data from the local filesystem

To move data from your machine into a volume, read the file locally and pass the contents to writeFile() / write_file().

Upload a single file

JavaScript & TypeScript

import fs from 'fs'
import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

// Read file from local filesystem
const content = fs.readFileSync('/local/path')
// Upload file to volume
await volume.writeFile('/path/in/volume', content)

Upload a directory

Iterate over the files in the directory and upload each one. The SDK does not currently provide a recursive upload helper, so nested directories need to be walked explicitly.

JavaScript & TypeScript

import fs from 'fs'
import path from 'path'
import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

const directoryPath = '/local/dir'
const files = fs.readdirSync(directoryPath)

for (const file of files) {
  const fullPath = path.join(directoryPath, file)

  // Skip directories
  if (!fs.statSync(fullPath).isFile()) continue

  const content = fs.readFileSync(fullPath)
  await volume.writeFile(`/upload/${file}`, content)
}

Downloading data to the local filesystem

Read the file from the volume with readFile() / read_file() and write the contents to disk.

JavaScript & TypeScript

import fs from 'fs'
import { Volume } from 'e2b'

const volume = await Volume.create('my-volume')

// Read file from volume
const content = await volume.readFile('/path/in/volume')
// Write file to local filesystem
fs.writeFileSync('/local/path', content)