Added docs on Volumes (#118)

* added volume docs

* updated docs

* diagram

* added examples, note

* added clarification

* removed diagram controls

* remove the diagram controls

* added standalone diagram

* updated volumes docs

Author: mishushakov

docs.json

@@ -166,6 +166,18 @@
               "docs/filesystem/download"
             ]
           },
+          {
+            "group": "Volumes",
+            "pages": [
+              "docs/volumes",
+              "docs/volumes/manage",
+              "docs/volumes/mount",
+              "docs/volumes/read-write",
+              "docs/volumes/info",
+              "docs/volumes/upload",
+              "docs/volumes/download"
+            ]
+          },
           {
             "group": "Commands",
             "pages": [

docs/volumes.mdx

@@ -0,0 +1,68 @@
+---
+title: "Volumes"
+sidebarTitle: Overview
+---
+
+Volumes provide persistent storage that exists independently of sandbox lifecycles. Data written to a volume persists even after a sandbox is shut down, and volumes can be mounted to multiple sandboxes over time.
+
+**One volume shared across multiple sandboxes**
+
+```mermaid actions={false}
+graph LR
+  V1[Volume A] --- S1[Sandbox 1]
+  V1 --- S2[Sandbox 2]
+  V1 --- S3[Sandbox 3]
+```
+
+**Each sandbox with its own volume**
+
+```mermaid actions={false}
+graph LR
+  V2[Volume A] --- S4[Sandbox 1]
+  V3[Volume B] --- S5[Sandbox 2]
+```
+
+**Standalone usage via SDK**
+
+```mermaid actions={false}
+graph LR
+  SDK[SDK] --- V4[Volume A]
+  SDK --- V5[Volume B]
+```
+
+When a volume is mounted to a sandbox, files can be read and written directly at the mount path. The SDK methods are meant to be used when the volume is not mounted to any sandbox.
+
+With E2B SDK you can:
+- [Manage volumes.](/docs/volumes/manage)
+- [Mount volumes to sandboxes.](/docs/volumes/mount)
+- [Read and write files to a volume.](/docs/volumes/read-write)
+- [Get file and directory metadata.](/docs/volumes/info)
+- [Upload data to a volume.](/docs/volumes/upload)
+- [Download data from a volume.](/docs/volumes/download)
+
+## Example
+
+<CodeGroup>
+```js JavaScript & TypeScript
+import { Volume, Sandbox } from 'e2b'
+
+const volume = await Volume.create('my-volume')
+
+const sandbox = await Sandbox.create({
+  volumeMounts: {
+    '/mnt/my-data': volume,
+  },
+})
+```
+```python Python
+from e2b import Volume, Sandbox
+
+volume = Volume.create('my-volume')
+
+sandbox = Sandbox.create(
+    volume_mounts={
+        '/mnt/my-data': volume,
+    },
+)
+```
+</CodeGroup>

docs/volumes/download.mdx

@@ -0,0 +1,31 @@
+---
+title: "Download data from volume"
+sidebarTitle: Download data
+---
+
+You can download data from a volume using the `readFile()` / `read_file()` method.
+
+<CodeGroup>
+```js 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)
+```
+```python Python
+from e2b import Volume
+
+volume = Volume.create('my-volume')
+
+# Read file from volume
+content = volume.read_file('/path/in/volume')
+# Write file to local filesystem
+with open('/local/path', 'w') as file:
+    file.write(content)
+```
+</CodeGroup>

docs/volumes/info.mdx

@@ -0,0 +1,188 @@
+---
+title: "Get information about a file or directory"
+sidebarTitle: File & directory metadata
+---
+
+You can get information about a file or directory in a volume using the `getInfo()` / `get_info()` method.
+
+### Getting information about a file
+
+<CodeGroup>
+```js 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,
+// }
+```
+```python Python
+from e2b import Volume
+
+volume = Volume.create('my-volume')
+
+# Create a new file
+volume.write_file('/test_file.txt', 'Hello, world!')
+
+# Get information about the file
+info = volume.get_info('/test_file.txt')
+
+print(info)
+# VolumeEntryStat(
+#   name='test_file.txt',
+#   type_='file',
+#   path='/test_file.txt',
+#   size=13,
+#   mode=0o644,
+#   uid=0,
+#   gid=0,
+#   atime=datetime(2025, 5, 26, 12, 0, 0),
+#   mtime=datetime(2025, 5, 26, 12, 0, 0),
+#   ctime=datetime(2025, 5, 26, 12, 0, 0),
+# )
+```
+</CodeGroup>
+
+### Getting information about a directory
+
+<CodeGroup>
+```js 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,
+// }
+```
+```python Python
+from e2b import Volume
+
+volume = Volume.create('my-volume')
+
+# Create a new directory
+volume.make_dir('/test_dir')
+
+# Get information about the directory
+info = volume.get_info('/test_dir')
+
+print(info)
+# VolumeEntryStat(
+#   name='test_dir',
+#   type_='directory',
+#   path='/test_dir',
+#   size=0,
+#   mode=0o755,
+#   uid=0,
+#   gid=0,
+#   atime=datetime(2025, 5, 26, 12, 0, 0),
+#   mtime=datetime(2025, 5, 26, 12, 0, 0),
+#   ctime=datetime(2025, 5, 26, 12, 0, 0),
+# )
+```
+</CodeGroup>
+
+### Checking if a path exists
+
+You can check whether a file or directory exists in a volume using the `exists()` method.
+
+<CodeGroup>
+```js 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
+```
+```python Python
+from e2b import Volume
+
+volume = Volume.create('my-volume')
+
+file_exists = volume.exists('/test_file.txt')
+print(file_exists)  # True or False
+```
+</CodeGroup>
+
+### Updating metadata
+
+You can update file or directory metadata such as user ID, group ID, and permissions mode using the `updateMetadata()` / `update_metadata()` method.
+
+<CodeGroup>
+```js 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,
+//   ...
+// }
+```
+```python Python
+from e2b import Volume
+
+volume = Volume.create('my-volume')
+
+volume.write_file('/test_file.txt', 'Hello, world!')
+
+updated = volume.update_metadata('/test_file.txt', uid=1000, gid=1000, mode=0o600)
+
+print(updated)
+# VolumeEntryStat(
+#   name='test_file.txt',
+#   type_='file',
+#   path='/test_file.txt',
+#   size=13,
+#   mode=0o600,
+#   uid=1000,
+#   gid=1000,
+#   ...
+# )
+```
+</CodeGroup>