feat: subpath mounts

.devcontainer/Dockerfile

@@ -13,6 +13,13 @@ RUN apt update && export DEBIAN_FRONTEND=noninteractive \
 RUN apt update && export DEBIAN_FRONTEND=noninteractive \
     && apt -y install --no-install-recommends openjdk-11-jdk protobuf-compiler libprotobuf-dev
 
+# Mount-s3 (AWS S3 FUSE driver)
+RUN /bin/bash -c 'apt update && export DEBIAN_FRONTEND=noninteractive \
+    && apt -y install --no-install-recommends fuse libfuse2 \
+    && MOUNT_S3_ARCH=$([ "$TARGETARCH" = "amd64" ] && echo "x86_64" || echo "arm64") \
+    && wget https://s3.amazonaws.com/mountpoint-s3-release/1.20.0/${MOUNT_S3_ARCH}/mount-s3-1.20.0-${MOUNT_S3_ARCH}.deb \
+    && apt install -y ./mount-s3-1.20.0-${MOUNT_S3_ARCH}.deb \
+    && rm -f mount-s3-1.20.0-${MOUNT_S3_ARCH}.deb'
 # Telepresence
 RUN curl -fL https://app.getambassador.io/download/tel2oss/releases/download/v2.17.0/telepresence-linux-${TARGETARCH} -o /usr/local/bin/telepresence && \
     chmod a+x /usr/local/bin/telepresence

apps/api/src/sandbox/dto/sandbox.dto.ts

@@ -25,6 +25,13 @@ export class SandboxVolume {
     example: '/data',
   })
   mountPath: string
+
+  @ApiPropertyOptional({
+    description:
+      'Optional subpath within the volume to mount. When specified, only this S3 prefix will be accessible. When omitted, the entire volume is mounted.',
+    example: 'users/alice',
+  })
+  subpath?: string
 }
 
 @ApiSchema({ name: 'Sandbox' })

apps/api/src/sandbox/runner-adapter/runnerAdapter.legacy.ts

@@ -193,6 +193,7 @@ export class RunnerAdapterLegacy implements RunnerAdapter {
       volumes: sandbox.volumes?.map((volume) => ({
         volumeId: volume.volumeId,
         mountPath: volume.mountPath,
+        subpath: volume.subpath,
       })),
       networkBlockAll: sandbox.networkBlockAll,
       networkAllowList: sandbox.networkAllowList,

apps/api/src/sandbox/services/sandbox.service.ts

@@ -64,7 +64,7 @@ import {
 import { RedisLockProvider } from '../common/redis-lock.provider'
 import { customAlphabet as customNanoid, nanoid, urlAlphabet } from 'nanoid'
 import { WithInstrumentation } from '../../common/decorators/otel.decorator'
-import { validateMountPaths } from '../utils/volume-mount-path-validation.util'
+import { validateMountPaths, validateSubpaths } from '../utils/volume-mount-path-validation.util'
 import { SandboxRepository } from '../repositories/sandbox.repository'
 import { PortPreviewUrlDto } from '../dto/port-preview-url.dto'
 
@@ -1375,7 +1375,13 @@ export class SandboxService {
     try {
       validateMountPaths(volumes)
     } catch (error) {
-      throw new BadRequestError(error instanceof Error ? error.message : 'Invalid volume mount paths')
+      throw new BadRequestError(error instanceof Error ? error.message : 'Invalid volume mount configuration')
+    }
+
+    try {
+      validateSubpaths(volumes)
+    } catch (error) {
+      throw new BadRequestError(error instanceof Error ? error.message : 'Invalid volume subpath configuration')
     }
 
     return volumes

apps/api/src/sandbox/utils/volume-mount-path-validation.util.ts

@@ -52,3 +52,48 @@ export function validateMountPaths(volumes: SandboxVolume[]): void {
     throw new Error(errors.join(', '))
   }
 }
+
+/**
+ * Validates subpaths for sandbox volumes to ensure they are safe S3 key prefixes
+ * @param volumes - Array of SandboxVolume objects to validate
+ * @throws Error with descriptive message if any subpath is invalid
+ */
+export function validateSubpaths(volumes: SandboxVolume[]): void {
+  const errors: string[] = []
+
+  for (const volume of volumes) {
+    const subpath = volume.subpath
+
+    // Empty/undefined subpath is valid (means mount entire volume)
+    if (!subpath) {
+      continue
+    }
+
+    if (typeof subpath !== 'string') {
+      errors.push(`Invalid subpath ${subpath} (must be a string)`)
+      continue
+    }
+
+    // S3 keys should not start with /
+    if (subpath.startsWith('/')) {
+      errors.push(`Invalid subpath "${subpath}" (S3 key prefixes cannot start with /)`)
+      continue
+    }
+
+    // Prevent path traversal
+    if (subpath.includes('..')) {
+      errors.push(`Invalid subpath "${subpath}" (cannot contain .. for security)`)
+      continue
+    }
+
+    // No consecutive slashes
+    if (subpath.includes('//')) {
+      errors.push(`Invalid subpath "${subpath}" (cannot contain consecutive slashes)`)
+      continue
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join(', '))
+  }
+}

apps/docs/src/content/docs/en/volumes.mdx

@@ -59,6 +59,14 @@ params = CreateSandboxFromSnapshotParams(
     volumes=[VolumeMount(volumeId=volume.id, mountPath=mount_dir_1)],
 )
 sandbox = daytona.create(params)
+
+# Mount a specific subpath within the volume
+# This is useful for isolating data or implementing multi-tenancy
+params = CreateSandboxFromSnapshotParams(
+    language="python",
+    volumes=[VolumeMount(volumeId=volume.id, mountPath=mount_dir_1, subpath="users/alice")],
+)
+sandbox2 = daytona.create(params)
 ```
 
 </TabItem>
@@ -79,6 +87,13 @@ const sandbox1 = await daytona.create({
   language: 'typescript',
   volumes: [{ volumeId: volume.id, mountPath: mountDir1 }],
 })
+
+// Mount a specific subpath within the volume
+// This is useful for isolating data or implementing multi-tenancy
+const sandbox2 = await daytona.create({
+  language: 'typescript',
+  volumes: [{ volumeId: volume.id, mountPath: mountDir, subpath: 'users/alice' }],
+})
 ```
 
 </TabItem>

apps/docs/src/content/docs/ja/volumes.mdx

@@ -55,6 +55,15 @@ sandbox = daytona.create(params)
 # サンドボックスを削除しても、ボリュームは保持されます
 sandbox.delete()
 
+# ボリューム内の特定のサブパスをマウントします
+# これは、データの分離やマルチテナントの実装に役立ちます
+params = CreateSandboxFromSnapshotParams(
+    language="python",
+    volumes=[VolumeMount(volumeId=volume.id, mountPath=mount_dir_1, subpath="users/alice")],
+)
+sandbox2 = daytona.create(params)
+
+sandbox2.delete()
 ```
 
 </TabItem>
@@ -80,6 +89,15 @@ async function main() {
   // サンドボックスの利用が終わったら、削除できます
   // サンドボックスを削除しても、ボリュームは保持されます
   await sandbox1.delete()
+
+  // ボリューム内の特定のサブパスをマウントします
+  // これは、データの分離やマルチテナントの実装に役立ちます
+  const sandbox2 = await daytona.create({
+    language: 'typescript',
+    volumes: [{ volumeId: volume.id, mountPath: mountDir1, subpath: 'users/alice' }],
+  })
+
+  await sandbox2.delete()
 }
 
 main()

apps/runner/pkg/api/dto/volume.go

@@ -4,6 +4,7 @@
 package dto
 
 type VolumeDTO struct {
-	VolumeId  string `json:"volumeId"`
-	MountPath string `json:"mountPath"`
+	VolumeId  string  `json:"volumeId"`
+	MountPath string  `json:"mountPath"`
+	Subpath   *string `json:"subpath,omitempty"`
 }

apps/runner/pkg/docker/volumes_mountpaths.go

@@ -5,11 +5,14 @@ package docker
 
 import (
 	"context"
+	"crypto/md5"
+	"encoding/hex"
 	"fmt"
 	"io"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 	"sync"
 
 	"github.com/daytonaio/runner/cmd/runner/config"
@@ -23,23 +26,31 @@ func (d *DockerClient) getVolumesMountPathBinds(ctx context.Context, volumes []d
 
 	for _, vol := range volumes {
 		volumeIdPrefixed := fmt.Sprintf("daytona-volume-%s", vol.VolumeId)
-		runnerVolumeMountPath := d.getRunnerVolumeMountPath(volumeIdPrefixed)
+		runnerVolumeMountPath := d.getRunnerVolumeMountPath(volumeIdPrefixed, vol.Subpath)
 
-		// Get or create mutex for this volume
+		// Create unique key for this volume+subpath combination for mutex
+		volumeKey := d.getVolumeKey(volumeIdPrefixed, vol.Subpath)
+
+		// Get or create mutex for this volume+subpath
 		d.volumeMutexesMutex.Lock()
-		volumeMutex, exists := d.volumeMutexes[volumeIdPrefixed]
+		volumeMutex, exists := d.volumeMutexes[volumeKey]
 		if !exists {
 			volumeMutex = &sync.Mutex{}
-			d.volumeMutexes[volumeIdPrefixed] = volumeMutex
+			d.volumeMutexes[volumeKey] = volumeMutex
 		}
 		d.volumeMutexesMutex.Unlock()
 
 		// Lock this specific volume's mutex
 		volumeMutex.Lock()
 		defer volumeMutex.Unlock()
 
+		subpathStr := ""
+		if vol.Subpath != nil {
+			subpathStr = *vol.Subpath
+		}
+
 		if d.isDirectoryMounted(runnerVolumeMountPath) {
-			log.Infof("volume %s is already mounted to %s", volumeIdPrefixed, runnerVolumeMountPath)
+			log.Infof("volume %s (subpath: %s) is already mounted to %s", volumeIdPrefixed, subpathStr, runnerVolumeMountPath)
 			volumeMountPathBinds = append(volumeMountPathBinds, fmt.Sprintf("%s/:%s/", runnerVolumeMountPath, vol.MountPath))
 			continue
 		}
@@ -49,40 +60,69 @@ func (d *DockerClient) getVolumesMountPathBinds(ctx context.Context, volumes []d
 			return nil, fmt.Errorf("failed to create mount directory %s: %s", runnerVolumeMountPath, err)
 		}
 
-		log.Infof("mounting S3 volume %s to %s", volumeIdPrefixed, runnerVolumeMountPath)
+		log.Infof("mounting S3 volume %s (subpath: %s) to %s", volumeIdPrefixed, subpathStr, runnerVolumeMountPath)
 
-		cmd := d.getMountCmd(ctx, volumeIdPrefixed, runnerVolumeMountPath)
+		cmd := d.getMountCmd(ctx, volumeIdPrefixed, vol.Subpath, runnerVolumeMountPath)
 		err = cmd.Run()
 		if err != nil {
-			return nil, fmt.Errorf("failed to mount S3 volume %s to %s: %s", volumeIdPrefixed, runnerVolumeMountPath, err)
+			return nil, fmt.Errorf("failed to mount S3 volume %s (subpath: %s) to %s: %s", volumeIdPrefixed, subpathStr, runnerVolumeMountPath, err)
 		}
 
-		log.Infof("mounted S3 volume %s to %s", volumeIdPrefixed, runnerVolumeMountPath)
+		log.Infof("mounted S3 volume %s (subpath: %s) to %s", volumeIdPrefixed, subpathStr, runnerVolumeMountPath)
 
 		volumeMountPathBinds = append(volumeMountPathBinds, fmt.Sprintf("%s/:%s/", runnerVolumeMountPath, vol.MountPath))
 	}
 
 	return volumeMountPathBinds, nil
 }
 
-func (d *DockerClient) getRunnerVolumeMountPath(volumeId string) string {
-	volumePath := filepath.Join("/mnt", volumeId)
+func (d *DockerClient) getRunnerVolumeMountPath(volumeId string, subpath *string) string {
+	// If subpath is provided, create a unique mount point for this volume+subpath combination
+	mountDirName := volumeId
+	if subpath != nil && *subpath != "" {
+		// Create a short hash of the subpath to keep the path reasonable
+		hash := md5.Sum([]byte(*subpath))
+		hashStr := hex.EncodeToString(hash[:])[:8]
+		mountDirName = fmt.Sprintf("%s-%s", volumeId, hashStr)
+	}
+
+	volumePath := filepath.Join("/mnt", mountDirName)
 	if config.GetEnvironment() == "development" {
-		volumePath = filepath.Join("/tmp", volumeId)
+		volumePath = filepath.Join("/tmp", mountDirName)
 	}
 
 	return volumePath
 }
 
+func (d *DockerClient) getVolumeKey(volumeId string, subpath *string) string {
+	if subpath == nil || *subpath == "" {
+		return volumeId
+	}
+	return fmt.Sprintf("%s:%s", volumeId, *subpath)
+}
+
 func (d *DockerClient) isDirectoryMounted(path string) bool {
 	cmd := exec.Command("mountpoint", path)
 	_, err := cmd.Output()
 
 	return err == nil
 }
 
-func (d *DockerClient) getMountCmd(ctx context.Context, volume, path string) *exec.Cmd {
-	cmd := exec.CommandContext(ctx, "mount-s3", "--allow-other", "--allow-delete", "--allow-overwrite", "--file-mode", "0666", "--dir-mode", "0777", volume, path)
+func (d *DockerClient) getMountCmd(ctx context.Context, volume string, subpath *string, path string) *exec.Cmd {
+	args := []string{"--allow-other", "--allow-delete", "--allow-overwrite", "--file-mode", "0666", "--dir-mode", "0777"}
+
+	if subpath != nil && *subpath != "" {
+		// Ensure subpath ends with /
+		prefix := *subpath
+		if !strings.HasSuffix(prefix, "/") {
+			prefix = prefix + "/"
+		}
+		args = append(args, "--prefix", prefix)
+	}
+
+	args = append(args, volume, path)
+
+	cmd := exec.CommandContext(ctx, "mount-s3", args...)
 
 	if d.awsEndpointUrl != "" {
 		cmd.Env = append(cmd.Env, "AWS_ENDPOINT_URL="+d.awsEndpointUrl)

examples/python/volumes/_async/volume.py

@@ -44,9 +44,28 @@ async def main():
         file = await sandbox2.fs.download_file(os.path.join(mount_dir_2, "new-file.txt"))
         print("File:", file)
 
+        # Mount a specific subpath within the volume
+        # This is useful for isolating data or implementing multi-tenancy
+        mount_dir_3 = "/home/daytona/subpath"
+
+        params = CreateSandboxFromSnapshotParams(
+            language="python",
+            volumes=[VolumeMount(volumeId=volume.id, mountPath=mount_dir_3, subpath="users/alice")],
+        )
+        sandbox3 = await daytona.create(params)
+
+        # This sandbox will only see files within the 'users/alice' subpath
+        # Create a file in the subpath
+        subpath_file = os.path.join(mount_dir_3, "alice-file.txt")
+        await sandbox3.fs.upload_file(b"Hello from Alice's subpath!", subpath_file)
+
+        # The file is stored at: volume-root/users/alice/alice-file.txt
+        # but appears at: /home/daytona/subpath/alice-file.txt in the sandbox
+
         # Cleanup
         await daytona.delete(sandbox)
         await daytona.delete(sandbox2)
+        await daytona.delete(sandbox3)
         # daytona.volume.delete(volume)
 
 

examples/python/volumes/volume.py

@@ -44,9 +44,28 @@ def main():
     file = sandbox2.fs.download_file(os.path.join(mount_dir_2, "new-file.txt"))
     print("File:", file)
 
+    # Mount a specific subpath within the volume
+    # This is useful for isolating data or implementing multi-tenancy
+    mount_dir_3 = "/home/daytona/subpath"
+
+    params = CreateSandboxFromSnapshotParams(
+        language="python",
+        volumes=[VolumeMount(volumeId=volume.id, mountPath=mount_dir_3, subpath="users/alice")],
+    )
+    sandbox3 = daytona.create(params)
+
+    # This sandbox will only see files within the 'users/alice' subpath
+    # Create a file in the subpath
+    subpath_file = os.path.join(mount_dir_3, "alice-file.txt")
+    sandbox3.fs.upload_file(b"Hello from Alice's subpath!", subpath_file)
+
+    # The file is stored at: volume-root/users/alice/alice-file.txt
+    # but appears at: /home/daytona/subpath/alice-file.txt in the sandbox
+
     # Cleanup
     daytona.delete(sandbox)
     daytona.delete(sandbox2)
+    daytona.delete(sandbox3)
     # daytona.volume.delete(volume)