feat: add Volume CRUD operations to SDKs

[mishushakov]

Summary

Add Volume CRUD operations to both TypeScript and Python SDKs. Volumes are persistent storage that can be mounted to sandboxes. Includes create, list, get_info, and destroy methods. Sandbox creation now supports volumeMounts parameter.

• Updated OpenAPI spec with volume endpoints and schemas
• Generated API clients for both SDKs using codegen
• Implemented Volume class in TypeScript with static methods
• Implemented sync/async Volume classes in Python with same API
• Added volumeMounts support to Sandbox creation flow
• Added volume tag to codegen filters for spec filtering

Usage Examples

TypeScript

import { Volume, Sandbox } from 'e2b'

// Create a volume
const volume = await Volume.create('my-data')
console.log(volume.volumeId, volume.name)

// List all volumes
const volumes = await Volume.list()

// Get volume info
const info = await Volume.getInfo(volume.volumeId)

// File operations on a volume
await volume.writeFile('/data/hello.txt', 'Hello, World!')
const content = await volume.readFile('/data/hello.txt')

// Directory operations
await volume.makeDir('/data/subdir', { force: true })
const entries = await volume.list('/data')

// Check if a path exists
const exists = await volume.exists('/data/hello.txt')

// Get file/directory info
const stat = await volume.getInfo('/data/hello.txt')

// Remove files
await volume.remove('/data/hello.txt')
await volume.remove('/data/subdir', { recursive: true })

// Mount a volume to a sandbox
const sandbox = await Sandbox.create('base', {
  volumeMounts: {
    '/mnt/data': volume,       // mount by Volume instance
    '/mnt/other': 'other-vol', // mount by volume name
  },
})

// Connect to an existing volume
const existing = await Volume.connect(volume.volumeId)

// Destroy a volume
await Volume.destroy(volume.volumeId)

Python (async)

from e2b import AsyncSandbox, AsyncVolume

# Create a volume
volume = await AsyncVolume.create("my-data")
print(volume.volume_id, volume.name)

# List all volumes
volumes = await AsyncVolume.list()

# Get volume info
info = await AsyncVolume.get_info(volume.volume_id)

# File operations on a volume
await volume.write_file("/data/hello.txt", "Hello, World!")
content = await volume.read_file("/data/hello.txt")

# Directory operations
await volume.make_dir("/data/subdir", force=True)
entries = await volume.list("/data")

# Check if a path exists
exists = await volume.exists("/data/hello.txt")

# Get file/directory info
stat = await volume.get_info("/data/hello.txt")

# Remove files
await volume.remove("/data/hello.txt")
await volume.remove("/data/subdir", recursive=True)

# Mount a volume to a sandbox
sandbox = await AsyncSandbox.create(
    "base",
    volume_mounts={
        "/mnt/data": volume,       # mount by Volume instance
        "/mnt/other": "other-vol", # mount by volume name
    },
)

# Connect to an existing volume
existing = await AsyncVolume.connect(volume.volume_id)

# Destroy a volume
await AsyncVolume.destroy(volume.volume_id)

Python (sync)

from e2b import Sandbox, Volume

# Create a volume
volume = Volume.create("my-data")
print(volume.volume_id, volume.name)

# List all volumes
volumes = Volume.list()

# Get volume info
info = Volume.get_info(volume.volume_id)

# File operations on a volume
volume.write_file("/data/hello.txt", "Hello, World!")
content = volume.read_file("/data/hello.txt")

# Directory operations
volume.make_dir("/data/subdir", force=True)
entries = volume.list("/data")

# Check if a path exists
exists = volume.exists("/data/hello.txt")

# Get file/directory info
stat = volume.get_info("/data/hello.txt")

# Remove files
volume.remove("/data/hello.txt")
volume.remove("/data/subdir", recursive=True)

# Mount a volume to a sandbox
sandbox = Sandbox.create(
    "base",
    volume_mounts={
        "/mnt/data": volume,       # mount by Volume instance
        "/mnt/other": "other-vol", # mount by volume name
    },
)

# Connect to an existing volume
existing = Volume.connect(volume.volume_id)

# Destroy a volume
Volume.destroy(volume.volume_id)

Testing

• TypeScript build passes with no type errors
• Python imports work and classes are instantiable
• Both SDKs pass format and lint checks
• Generated API client models use correct field mappings (id/name)

---

Note

Medium Risk
Introduces new client surface area for volume CRUD and file operations plus wiring volume mounts into sandbox creation, which affects API request shapes and authentication tokens. Risk is moderate due to largely additive changes but touches core SDK entrypoints and generated API models.

Overview
Adds first-class Volumes support to both SDKs: JS exports a new Volume client (CRUD plus directory/file ops via a new volume-content OpenAPI client), and Python exposes Volume/AsyncVolume with generated volume endpoints and content client.

Extends sandbox creation in both JS and Python to accept volumeMounts/volume_mounts (mount-path → volume name or instance) and propagates mounts into returned sandbox info. Also updates generated API schemas (new /volumes endpoints, VolumeAndToken, log filtering params), bumps tooling/scripts for volume spec generation, and adds comprehensive JS volume tests/fixtures plus a changeset for minor releases.

^{Written by Cursor Bugbot for commit 7995449. This will update automatically on new commits. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 7995449

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@e2b/python-sdk	Minor
e2b	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[mishushakov]

@djeebus no need to review, it's a draft

[github-actions]

Package Artifacts

Built from d0b3ca7. Download artifacts from this workflow run.

JS SDK (e2b@2.14.2-mishushakov-volume-crud-sdk.0):

npm install ./e2b-2.14.2-mishushakov-volume-crud-sdk.0.tgz

CLI (@e2b/cli@2.8.2-mishushakov-volume-crud-sdk.0):

npm install ./e2b-cli-2.8.2-mishushakov-volume-crud-sdk.0.tgz

Python SDK (e2b==2.15.2+mishushakov-volume-crud-sdk):

pip install ./e2b-2.15.2+mishushakov.volume.crud.sdk-py3-none-any.whl

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8ae99f53cf

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

Volume remove makes redundant API call on every invocation

Medium Severity

The remove method always makes an extra getInfo/get_info API call before every delete operation to determine if the path is a file or directory (to choose between DELETE /file and DELETE /dir). This doubles the number of API requests for every remove operation. For non-existent paths, this results in two failed requests: getInfo returns 404 (caught and swallowed), then DELETE /file also returns 404 (thrown). There's also a TOCTOU race condition: the entry type could change between the getInfo check and the DELETE call, causing the wrong endpoint to be used.

Additional Locations (1)

• packages/python-sdk/e2b/volume/volume_async.py#L575-L581

 

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Volume content API uses wrong paths, missing volumeID
  • Updated all volume content API methods (list, makeDir, getInfo, readFile, writeFile, updateMetadata, remove) to use the correct schema paths (/volumecontent/{volumeID}/dir, /volumecontent/{volumeID}/file, /volumecontent/{volumeID}/stat) and include the volumeID path parameter in params.path.

Or push these changes by commenting:

@cursor push 2cfc103f88

Preview (2cfc103f88)

diff --git a/packages/js-sdk/src/volume/index.ts b/packages/js-sdk/src/volume/index.ts
--- a/packages/js-sdk/src/volume/index.ts
+++ b/packages/js-sdk/src/volume/index.ts
@@ -227,8 +227,11 @@
     const config = new VolumeConnectionConfig(this, opts)
     const client = new VolumeApiClient(config)
 
-    const res = await client.api.GET('/dir', {
+    const res = await client.api.GET('/volumecontent/{volumeID}/dir', {
       params: {
+        path: {
+          volumeID: this.volumeId,
+        },
         query: {
           path,
           depth: opts?.depth,
@@ -265,8 +268,11 @@
     const config = new VolumeConnectionConfig(this, opts)
     const client = new VolumeApiClient(config)
 
-    const res = await client.api.POST('/dir', {
+    const res = await client.api.POST('/volumecontent/{volumeID}/dir', {
       params: {
+        path: {
+          volumeID: this.volumeId,
+        },
         query: {
           path,
           uid: opts?.uid,
@@ -308,8 +314,11 @@
     const config = new VolumeConnectionConfig(this, opts)
     const client = new VolumeApiClient(config)
 
-    const res = await client.api.GET('/stat', {
+    const res = await client.api.GET('/volumecontent/{volumeID}/stat', {
       params: {
+        path: {
+          volumeID: this.volumeId,
+        },
         query: {
           path,
         },
@@ -375,8 +384,11 @@
     const config = new VolumeConnectionConfig(this, opts)
     const client = new VolumeApiClient(config)
 
-    const res = await client.api.PATCH('/file', {
+    const res = await client.api.PATCH('/volumecontent/{volumeID}/file', {
       params: {
+        path: {
+          volumeID: this.volumeId,
+        },
         query: {
           path,
         },
@@ -477,8 +489,11 @@
     const config = new VolumeConnectionConfig(this, opts)
     const client = new VolumeApiClient(config)
 
-    const res = await client.api.GET('/file', {
+    const res = await client.api.GET('/volumecontent/{volumeID}/file', {
       params: {
+        path: {
+          volumeID: this.volumeId,
+        },
         query: {
           path,
         },
@@ -535,8 +550,11 @@
 
     const blob = await toBlob(data)
 
-    const res = await client.api.PUT('/file', {
+    const res = await client.api.PUT('/volumecontent/{volumeID}/file', {
       params: {
+        path: {
+          volumeID: this.volumeId,
+        },
         query: {
           path,
           uid: opts?.uid,
@@ -595,10 +613,13 @@
       }
     }
 
-    const endpoint = isDirectory ? '/dir' : '/file'
+    const endpoint = isDirectory ? '/volumecontent/{volumeID}/dir' : '/volumecontent/{volumeID}/file'
 
     const res = await client.api.DELETE(endpoint, {
       params: {
+        path: {
+          volumeID: this.volumeId,
+        },
         query: {
           path,
           recursive: isDirectory ? opts?.recursive : undefined,

_{This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}