fix(volume): align API with E2B SDK

crates/aenv/src/client/sandboxes.rs

@@ -5,6 +5,23 @@ use serde_json::json;
 use std::collections::HashMap;
 use std::time::Duration;
 
+#[derive(Debug, Serialize)]
+pub struct SandboxVolumeMount {
+    pub name: String,
+    pub path: String,
+}
+
+fn volume_mounts_request(
+    mounts: Option<HashMap<String, String>>,
+) -> Option<Vec<SandboxVolumeMount>> {
+    mounts.map(|mounts| {
+        mounts
+            .into_iter()
+            .map(|(path, name)| SandboxVolumeMount { name, path })
+            .collect()
+    })
+}
+
 #[derive(Debug, Serialize)]
 pub struct NewSandbox<'a> {
     #[serde(rename = "templateID")]
@@ -13,7 +30,7 @@ pub struct NewSandbox<'a> {
     pub timeout: Option<u32>,
     pub secure: bool,
     #[serde(skip_serializing_if = "Option::is_none", rename = "volumeMounts")]
-    pub volume_mounts: Option<HashMap<String, String>>,
+    pub volume_mounts: Option<Vec<SandboxVolumeMount>>,
 }
 
 #[derive(Debug, Serialize)]
@@ -29,7 +46,7 @@ pub struct NewColdSandbox<'a> {
     pub disk_size_mb: Option<u32>,
     pub secure: bool,
     #[serde(skip_serializing_if = "Option::is_none", rename = "volumeMounts")]
-    pub volume_mounts: Option<HashMap<String, String>>,
+    pub volume_mounts: Option<Vec<SandboxVolumeMount>>,
 }
 
 #[derive(Deserialize)]
@@ -86,7 +103,7 @@ impl Client {
             template_id,
             timeout,
             secure: true,
-            volume_mounts,
+            volume_mounts: volume_mounts_request(volume_mounts),
         };
         let resp = handle_status(self.post("/sandboxes").send_json(&body))?;
         let sandbox: Sandbox = resp.into_json()?;
@@ -110,7 +127,7 @@ impl Client {
             memory_mb,
             disk_size_mb,
             secure: true,
-            volume_mounts,
+            volume_mounts: volume_mounts_request(volume_mounts),
         };
         let resp = handle_status(self.post("/sandboxes-cold").send_json(&body))?;
         let sandbox: Sandbox = resp.into_json()?;

docs/src/concepts/volumes.md

@@ -206,9 +206,12 @@ curl -fsS -X POST "$AENV_URL/sandboxes" \
   -H "Content-Type: application/json" \
   -d '{
     "templateID": "ubuntu",
-    "volumeMounts": {
-      "/workspace/data": "job-42-data"
-    }
+    "volumeMounts": [
+      {
+        "name": "job-42-data",
+        "path": "/workspace/data"
+      }
+    ]
   }'
 ```
 

docs/src/integration/e2b.md

@@ -64,6 +64,38 @@ await sandbox.kill();
 
 Replace `<template-id>` with a template that exists in your local template store. Use `e2b template list` or `GET /v2/templates` to see available templates.
 
+### Volume mounts
+
+The TypeScript SDK can create a volume and pass it directly when creating a
+sandbox:
+
+```typescript
+import { Sandbox, Volume } from "e2b";
+
+const volume = await Volume.create("workspace-volume", {
+  apiKey: process.env.E2B_API_KEY,
+});
+const sandbox = await Sandbox.create("<template-id>", {
+  apiKey: process.env.E2B_API_KEY,
+  volumeMounts: {
+    "/workspace": volume,
+  },
+});
+```
+
+For the Python SDK, create the volume with `aenv volume create` or
+`POST /volumes`, then pass its name when creating a sandbox:
+
+```python
+sandbox = Sandbox.create(
+    "<template-id>",
+    volume_mounts={"/workspace": "workspace-volume"},
+)
+```
+
+AgentENV supports the TypeScript SDK's volume create, list, and delete operations, and accessing the mounted filesystem through the sandbox.
+The E2B SDK's direct volume content API is not supported.
+
 ### Python SDK
 
 #### Setup