Volumes (#346)

Signed-off-by: Vedran Jukic <[email protected]>
Signed-off-by: MDzaja <[email protected]>
Co-authored-by: Vedran Jukic <[email protected]>

Author: MDzaja

package.json

@@ -2,7 +2,7 @@
   "name": "docs",
   "license": "Apache-2.0",
   "type": "module",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "scripts": {
     "postinstall": "is-ci || husky",
     "dev": "astro dev --host",

public/llms-full.txt

@@ -1,5 +1,5 @@
-# Daytona Documentation v0.16.0
-# Generated on: 2025-05-05
+# Daytona Documentation v0.17.0
+# Generated on: 2025-05-07
 
 
 title: API Keys
@@ -2156,7 +2156,7 @@ Setting the auto-stop interval parameter to `0` will disable the auto-stop funct
 
 ### Basic Sandbox Creation
 
-Daytona SDK provides methods to create Sandboxes with default configurations, specific languages, or custom IDs using Python and TypeScript.
+Daytona SDK provides methods to create Sandboxes with default configurations, specific languages, or custom labels using Python and TypeScript.
 
 ```python
 from daytona_sdk import Daytona
@@ -2172,9 +2172,9 @@ sandbox = daytona.create()
 params = CreateSandboxParams(language="python")
 sandbox = daytona.create(params)
 
-# Create a Sandbox with custom ID
+# Create a Sandbox with custom labels
 
-params = CreateSandboxParams(id="my-sandbox")
+params = CreateSandboxParams(labels={"SOME_LABEL": "my-label"})
 sandbox = daytona.create(params)
 
 ```
@@ -2189,13 +2189,13 @@ const sandbox = await daytona.create();
 // Create a Sandbox with specific language
 const sandbox = await daytona.create({ language: 'typescript' });
 
-// Create a Sandbox with custom ID
-const sandbox = await daytona.create({ id: 'my-sandbox' });
+// Create a Sandbox with custom labels
+const sandbox = await daytona.create({ labels: { SOME_LABEL: 'my-label' } });
 ```
 
 
 :::note
-Daytona keeps a pool of ready-to-go "warm" Sandboxes. When available, they are automatically used if a custom ID _isn't_ provided and the default image is used, reducing the creation time down to a fraction of a second.
+Daytona keeps a pool of ready-to-go "warm" Sandboxes. When available, they are automatically used if the default image is used, reducing the creation time down to a fraction of a second.
 :::
 
 ### Sandbox Resources
@@ -2794,6 +2794,103 @@ The Images Quota is the maximum number of Images that can be created in an Organ
 
 The Total image size Quota is the maximum amount of disk space that can be used by Images in an Organization expressed in gigabytes.
 
+title: Volumes
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Volumes are FUSE-based mounts on the Sandbox file system that enable file sharing between Sandboxes and instant access to existing files already present on the mounted volume.
+Using Volumes the Sandboxes can instantly read from large files eliminating the need to upload them first to the Sandbox file system.
+The volume data is stored on the S3 compatible object store. Multiple volumes can be mounted to a single Sandbox and each volume can be mounted on multiple Sandboxes simultaneously.
+
+## Creating Volumes
+
+In order to mount a volume to a Sandbox, one must be created.
+
+```bash
+volume = daytona.volume.get("my-volume", create=True)
+```
+```bash
+const volume = await daytona.volume.get('my-volume', true)
+```
+
+## Mounting Volumes to Sandboxes
+
+Once a volume is created, it can be mounted to a Sandbox by specifying it in the `CreateSandboxParams` object:
+
+```python
+import os
+from daytona_sdk import CreateSandboxParams, Daytona, VolumeMount
+
+daytona = Daytona()
+
+# Create a new volume or get an existing one
+volume = daytona.volume.get("my-volume", create=True)
+
+# Mount the volume to the sandbox
+mount_dir_1 = "/home/daytona/volume"
+
+params = CreateSandboxParams(
+    language="python",
+    volumes=[VolumeMount(volumeId=volume.id, mountPath=mount_dir_1)],
+)
+sandbox = daytona.create(params)
+
+# When you're done with the sandbox, you can remove it
+# The volume will persist even after the sandbox is removed
+daytona.remove(sandbox)
+
+```
+
+```typescript
+import { Daytona } from '@daytonaio/sdk'
+import path from 'path'
+
+async function main() {
+  const daytona = new Daytona()
+
+  //  Create a new volume or get an existing one
+  const volume = await daytona.volume.get('my-volume', true)
+
+  // Mount the volume to the sandbox
+  const mountDir1 = '/home/daytona/volume'
+
+  const sandbox1 = await daytona.create({
+    language: 'typescript',
+    volumes: [{ volumeId: volume.id, mountPath: mountDir1 }],
+  })
+  
+  // When you're done with the sandbox, you can remove it
+  // The volume will persist even after the sandbox is removed
+  await daytona.remove(sandbox1)
+}
+
+main()
+
+```
+
+
+## Deleting Volumes
+
+When a volume is no longer needed, it can be removed.
+
+```python
+volume = daytona.volume.get("my-volume", create=True)
+daytona.volume.delete(volume)
+```
+```typescript
+const volume = await daytona.volume.get('my-volume', true)
+await daytona.volume.delete(volume)
+```
+
+## Working with Volumes
+
+Once mounted, you can read from and write to the volume just like any other directory in the Sandbox file system. Files written to the volume persist beyond the lifecycle of any individual Sandbox.
+
+## Limitations
+
+Since volumes are FUSE-based mounts, they can not be used for applications that require block storage access (like database tables).
+Volumes are generally slower for both read and write operations compared to the local Sandbox file system.
+
 title: Web Terminal
 
 import { Tabs, TabItem } from '@astrojs/starlight/components';

public/llms.txt

@@ -1,5 +1,5 @@
-# Daytona Documentation v0.16.0
-# Generated on: 2025-05-05
+# Daytona Documentation v0.17.0
+# Generated on: 2025-05-07
 
 # Daytona
 
@@ -145,4 +145,10 @@
 - [Disk Quota](https://daytona.io/docs/usage#disk-quota)
 - [Sandboxes/Running Sandboxes Quota](https://daytona.io/docs/usage#sandboxesrunning-sandboxes-quota)
 - [Images/Total Image Size Quota](https://daytona.io/docs/usage#imagestotal-image-size-quota)
+- [Volumes](https://daytona.io/docs/volumes)
+- [Creating Volumes](https://daytona.io/docs/volumes#creating-volumes)
+- [Mounting Volumes to Sandboxes](https://daytona.io/docs/volumes#mounting-volumes-to-sandboxes)
+- [Deleting Volumes](https://daytona.io/docs/volumes#deleting-volumes)
+- [Working with Volumes](https://daytona.io/docs/volumes#working-with-volumes)
+- [Limitations](https://daytona.io/docs/volumes#limitations)
 - [Web Terminal](https://daytona.io/docs/web-terminal)

public/search.json

@@ -1121,7 +1121,7 @@
   },
   {
     "title": "Basic Sandbox Creation",
-    "description": "Daytona SDK provides methods to create Sandboxes with default configurations, specific languages, or custom IDs using Python and TypeScript.",
+    "description": "Daytona SDK provides methods to create Sandboxes with default configurations, specific languages, or custom labels using Python and TypeScript.",
     "tag": "Documentation",
     "url": "/docs/sandbox-management#basic-sandbox-creation",
     "slug": "/sandbox-management#basic-sandbox-creation",
@@ -1144,11 +1144,11 @@
     "objectID": 143
   },
   {
-    "title": "Create a Sandbox with custom ID",
+    "title": "Create a Sandbox with custom labels",
     "description": "",
     "tag": "Documentation",
-    "url": "/docs/sandbox-management#create-a-sandbox-with-custom-id",
-    "slug": "/sandbox-management#create-a-sandbox-with-custom-id",
+    "url": "/docs/sandbox-management#create-a-sandbox-with-custom-labels",
+    "slug": "/sandbox-management#create-a-sandbox-with-custom-labels",
     "objectID": 144
   },
   {
@@ -1535,12 +1535,92 @@
     "slug": "/usage#imagestotal-image-size-quota",
     "objectID": 192
   },
+  {
+    "title": "Volumes",
+    "description": "Volumes are FUSE-based mounts on the Sandbox file system that enable file sharing between Sandboxes and instant access to existing files already present on the mounted volume.",
+    "tag": "Documentation",
+    "url": "/docs/volumes",
+    "slug": "/volumes",
+    "objectID": 193
+  },
+  {
+    "title": "Creating Volumes",
+    "description": "In order to mount a volume to a Sandbox, one must be created.",
+    "tag": "Documentation",
+    "url": "/docs/volumes#creating-volumes",
+    "slug": "/volumes#creating-volumes",
+    "objectID": 194
+  },
+  {
+    "title": "Mounting Volumes to Sandboxes",
+    "description": "Once a volume is created, it can be mounted to a Sandbox by specifying it in the `CreateSandboxParams` object:",
+    "tag": "Documentation",
+    "url": "/docs/volumes#mounting-volumes-to-sandboxes",
+    "slug": "/volumes#mounting-volumes-to-sandboxes",
+    "objectID": 195
+  },
+  {
+    "title": "Create a new volume or get an existing one",
+    "description": "",
+    "tag": "Documentation",
+    "url": "/docs/volumes#create-a-new-volume-or-get-an-existing-one",
+    "slug": "/volumes#create-a-new-volume-or-get-an-existing-one",
+    "objectID": 196
+  },
+  {
+    "title": "Mount the volume to the sandbox",
+    "description": "",
+    "tag": "Documentation",
+    "url": "/docs/volumes#mount-the-volume-to-the-sandbox",
+    "slug": "/volumes#mount-the-volume-to-the-sandbox",
+    "objectID": 197
+  },
+  {
+    "title": "When you're done with the sandbox, you can remove it",
+    "description": "",
+    "tag": "Documentation",
+    "url": "/docs/volumes#when-youre-done-with-the-sandbox-you-can-remove-it",
+    "slug": "/volumes#when-youre-done-with-the-sandbox-you-can-remove-it",
+    "objectID": 198
+  },
+  {
+    "title": "The volume will persist even after the sandbox is removed",
+    "description": "",
+    "tag": "Documentation",
+    "url": "/docs/volumes#the-volume-will-persist-even-after-the-sandbox-is-removed",
+    "slug": "/volumes#the-volume-will-persist-even-after-the-sandbox-is-removed",
+    "objectID": 199
+  },
+  {
+    "title": "Deleting Volumes",
+    "description": "When a volume is no longer needed, it can be removed.",
+    "tag": "Documentation",
+    "url": "/docs/volumes#deleting-volumes",
+    "slug": "/volumes#deleting-volumes",
+    "objectID": 200
+  },
+  {
+    "title": "Working with Volumes",
+    "description": "Once mounted, you can read from and write to the volume just like any other directory in the Sandbox file system.",
+    "tag": "Documentation",
+    "url": "/docs/volumes#working-with-volumes",
+    "slug": "/volumes#working-with-volumes",
+    "objectID": 201
+  },
+  {
+    "title": "Limitations",
+    "description": "Since volumes are FUSE-based mounts, they can not be used for applications that require block storage access (like database tables).",
+    "tag": "Documentation",
+    "url": "/docs/volumes#limitations",
+    "slug": "/volumes#limitations",
+    "objectID": 202
+  },
   {
     "title": "Web Terminal",
     "description": "Daytona provides a Web Terminal for interacting with your Sandboxes, allowing for a convenient way to view files, run commands, and debug.",
     "tag": "Documentation",
     "url": "/docs/web-terminal",
     "slug": "/web-terminal",
-    "objectID": 193
+    "objectID": 203
   }
 ]

src/content/config.ts

@@ -277,6 +277,15 @@ export const sidebarConfig: NavigationGroup[] = [
           icon: 'server.svg',
         },
       },
+      {
+        type: 'link',
+        href: '/docs/volumes',
+        label: 'Volumes',
+        description: 'Learn how to manage volumes in your Daytona Sandboxes.',
+        attrs: {
+          icon: 'container-registries.svg',
+        },
+      },
     ],
   },
   {

src/content/docs/python-sdk/daytona.mdx

@@ -19,6 +19,7 @@ It can be initialized either with explicit configuration or using environment va
 - `api_key` _str_ - API key for authentication.
 - `api_url` _str_ - URL of the Daytona API.
 - `target` _str_ - Default target location for Sandboxes.
+- `volume` _VolumeService_ - Service for managing volumes.
 
 **Example**:
 
@@ -117,7 +118,7 @@ params = CreateSandboxParams(
     language="python",
     image="debian:12.9",
     env_vars={"DEBUG": "true"},
-    resources=SandboxResources(cpu=2, memory=4096),
+    resources=SandboxResources(cpu=2, memory=4),
     auto_stop_interval=0
 )
 sandbox = daytona.create(params, 40)

src/content/docs/python-sdk/file-system.mdx

@@ -22,7 +22,7 @@ be performed within a Daytona Sandbox.
 
 ```python
 def __init__(instance: SandboxInstance, toolbox_api: ToolboxApi,
-             root_dir: str)
+             get_root_dir: Callable[[], str])
 ```
 
 Initializes a new FileSystem instance.
@@ -31,7 +31,7 @@ Initializes a new FileSystem instance.
 
 - `instance` _SandboxInstance_ - The Sandbox instance this file system belongs to.
 - `toolbox_api` _ToolboxApi_ - API client for Sandbox operations.
-- `root_dir` _str_ - The default root directory of the Sandbox.
+- `get_root_dir` _Callable[[], str]_ - A function to get the default root directory of the Sandbox.
 
 #### FileSystem.create\_folder
 

src/content/docs/python-sdk/git.mdx

@@ -43,7 +43,7 @@ sandbox.git.commit(
 
 ```python
 def __init__(sandbox: "Sandbox", toolbox_api: ToolboxApi,
-             instance: SandboxInstance, root_dir: str)
+             instance: SandboxInstance, get_root_dir: Callable[[], str])
 ```
 
 Initializes a new Git handler instance.
@@ -53,7 +53,7 @@ Initializes a new Git handler instance.
 - `sandbox` _Sandbox_ - The parent Sandbox instance.
 - `toolbox_api` _ToolboxApi_ - API client for Sandbox operations.
 - `instance` _SandboxInstance_ - The Sandbox instance this Git handler belongs to.
-- `root_dir` _str_ - The default root directory of the Sandbox.
+- `get_root_dir` _Callable[[], str]_ - A function to get the default root directory of the Sandbox.
 
 #### Git.add