feat: persist volume path to database and pass through gRPC

packages/api/internal/handlers/sandbox_create.go

@@ -375,10 +375,11 @@ func convertAPIVolumesToOrchestratorVolumes(ctx context.Context, sqlClient *sqlc
 		usedPaths[v.Path] = struct{}{}
 
 		results = append(results, &orchestrator.SandboxVolumeMount{
-			Id:   actualVolume.ID.String(),
-			Path: v.Path,
-			Type: actualVolume.VolumeType,
-			Name: actualVolume.Name,
+			Id:         actualVolume.ID.String(),
+			Path:       v.Path,
+			Type:       actualVolume.VolumeType,
+			Name:       actualVolume.Name,
+			VolumePath: actualVolume.VolumePath,
 		})
 	}
 

packages/api/internal/handlers/sandbox_resume.go

@@ -175,12 +175,16 @@ func convertDatabaseMountsToOrchestratorMounts(volumes []*types.SandboxVolumeMou
 	results := make([]*orchestratorgrpc.SandboxVolumeMount, 0, len(volumes))
 
 	for _, item := range volumes {
-		results = append(results, &orchestratorgrpc.SandboxVolumeMount{
+		mount := &orchestratorgrpc.SandboxVolumeMount{
 			Id:   item.ID,
 			Type: item.Type,
 			Name: item.Name,
 			Path: item.Path,
-		})
+		}
+		if item.VolumePath != "" {
+			mount.VolumePath = &item.VolumePath
+		}
+		results = append(results, mount)
 	}
 
 	return results

packages/api/internal/handlers/volume_create.go

@@ -106,7 +106,8 @@ func (a *APIStore) PostVolumes(c *gin.Context) {
 	default:
 	}
 
-	if err := a.createVolume(ctx, clusterID, volume); err != nil {
+	volumePath, err := a.createVolume(ctx, clusterID, volume)
+	if err != nil {
 		if errors.Is(err, ErrClusterNotFound) {
 			a.sendAPIStoreError(c, http.StatusServiceUnavailable, "Cluster not found")
 			telemetry.ReportError(ctx, "cluster not found", err)
@@ -127,6 +128,20 @@ func (a *APIStore) PostVolumes(c *gin.Context) {
 		return
 	}
 
+	// Persist the volume path returned by the orchestrator.
+	if volumePath != "" {
+		if err := client.UpdateVolumePath(ctx, queries.UpdateVolumePathParams{
+			VolumePath: &volumePath,
+			VolumeID:   volume.ID,
+			TeamID:     volume.TeamID,
+		}); err != nil {
+			telemetry.ReportCriticalError(ctx, "failed to update volume path", err)
+			// Non-fatal: the volume was created successfully, path is optional.
+		} else {
+			volume.VolumePath = &volumePath
+		}
+	}
+
 	if err := tx.Commit(ctx); err != nil {
 		go func(ctx context.Context) {
 			if err := a.deleteVolume(ctx, clusterID, volume); err != nil {
@@ -180,12 +195,20 @@ func isValidVolumeName(name string) bool {
 	return validVolumeNameRegex.MatchString(name)
 }
 
-func (a *APIStore) createVolume(ctx context.Context, clusterID uuid.UUID, volume queries.Volume) error {
-	return a.executeOnOrchestratorByClusterID(ctx, clusterID, func(ctx context.Context, client *clusters.GRPCClient) error {
-		_, err := client.Volumes.CreateVolume(ctx, &orchestrator.CreateVolumeRequest{
+func (a *APIStore) createVolume(ctx context.Context, clusterID uuid.UUID, volume queries.Volume) (string, error) {
+	var volumePath string
+	err := a.executeOnOrchestratorByClusterID(ctx, clusterID, func(ctx context.Context, client *clusters.GRPCClient) error {
+		resp, err := client.Volumes.CreateVolume(ctx, &orchestrator.CreateVolumeRequest{
 			Volume: toVolumeKey(volume),
 		})
+		if err != nil {
+			return err
+		}
+
+		volumePath = resp.GetVolumePath()
 
-		return err
+		return nil
 	})
+
+	return volumePath, err
 }

packages/api/internal/handlers/volume_token.go

@@ -35,6 +35,11 @@ func generateVolumeContentToken(config cfg.VolumesTokenConfig, volume queries.Vo
 		"voltype": volume.VolumeType,
 	}
 
+	// Include volume path in the token only if it's been persisted.
+	if volume.VolumePath != nil && *volume.VolumePath != "" {
+		claims["volpath"] = *volume.VolumePath
+	}
+
 	token := jwt.NewWithClaims(config.SigningMethod, claims)
 	token.Header["tokid"] = config.SigningKeyName
 	signedToken, err := token.SignedString(config.SigningKey)

packages/api/internal/handlers/volume_util.go

@@ -28,6 +28,7 @@ func toVolumeKey(volume queries.Volume) *orchestrator.VolumeInfo {
 		VolumeId:   volume.ID.String(),
 		VolumeType: volume.VolumeType,
 		TeamId:     volume.TeamID.String(),
+		VolumePath: volume.VolumePath,
 	}
 }
 

packages/api/internal/orchestrator/nodemanager/sandboxes.go

@@ -132,10 +132,11 @@ func ConvertOrchestratorMountsToDatabaseMounts(mounts []*orchestrator.SandboxVol
 
 	for _, item := range mounts {
 		results = append(results, &types.SandboxVolumeMountConfig{
-			ID:   item.GetId(),
-			Type: item.GetType(),
-			Name: item.GetName(),
-			Path: item.GetPath(),
+			ID:         item.GetId(),
+			Type:       item.GetType(),
+			Name:       item.GetName(),
+			Path:       item.GetPath(),
+			VolumePath: item.GetVolumePath(),
 		})
 	}
 

packages/db/migrations/20260401000000_add_volume_path.sql

@@ -0,0 +1,5 @@
+-- +goose Up
+ALTER TABLE volumes ADD COLUMN volume_path TEXT;
+
+-- +goose Down
+ALTER TABLE volumes DROP COLUMN IF EXISTS volume_path;

packages/db/pkg/types/types.go

@@ -81,10 +81,11 @@ type SandboxNetworkConfig struct {
 }
 
 type SandboxVolumeMountConfig struct {
-	ID   string `json:"id"`
-	Type string `json:"type"`
-	Name string `json:"name"`
-	Path string `json:"path"`
+	ID         string `json:"id"`
+	Type       string `json:"type"`
+	Name       string `json:"name"`
+	Path       string `json:"path"`
+	VolumePath string `json:"volume_path,omitempty"`
 }
 
 type SandboxAutoResumePolicy string

packages/db/queries/volumes/volumes.sql

@@ -1,6 +1,6 @@
 -- name: CreateVolume :one
-INSERT INTO volumes (team_id, volume_type, name)
-VALUES (@team_id, @volume_type, @name)
+INSERT INTO volumes (team_id, volume_type, name, volume_path)
+VALUES (@team_id, @volume_type, @name, @volume_path)
 RETURNING *;
 
 -- name: GetVolume :one
@@ -16,3 +16,6 @@ SELECT * FROM volumes WHERE team_id = @team_id;
 
 -- name: DeleteVolume :exec
 DELETE FROM volumes WHERE team_id = @team_id AND id = @volume_id;
+
+-- name: UpdateVolumePath :exec
+UPDATE volumes SET volume_path = @volume_path WHERE id = @volume_id AND team_id = @team_id;

packages/orchestrator/orchestrator.proto

@@ -65,6 +65,7 @@ message SandboxVolumeMount {
   string path = 2;
   string type = 3;
   string name = 4;
+  optional string volume_path = 5;
 }
 
 message SandboxNetworkConfig {

packages/orchestrator/pkg/chrooted/builder.go

@@ -35,6 +35,16 @@ func (b *Builder) Chroot(ctx context.Context, volumeType string, teamID, volumeI
 	return fs, nil
 }
 
+// ChrootPath creates a chrooted filesystem at the given path directly, bypassing volume type lookup.
+func (b *Builder) ChrootPath(ctx context.Context, fullPath string, volumeID uuid.UUID) (*Chrooted, error) {
+	fs, err := Chroot(ctx, fullPath, WithMetadata("volume-id", volumeID.String()))
+	if err != nil {
+		return nil, err
+	}
+
+	return fs, nil
+}
+
 func (b *Builder) BuildVolumePath(volumeType string, teamID, volumeID uuid.UUID) (string, error) {
 	volumeTypeRoot, ok := b.config.PersistentVolumeMounts[volumeType]
 	if !ok {

packages/orchestrator/pkg/nfsproxy/chroot/nfs.go

@@ -168,7 +168,14 @@ func (h *NFSHandler) getChroot(ctx context.Context, remoteAddr net.Addr, request
 		return nil, ErrVolumeID
 	}
 
-	fs, err := h.builder.Chroot(ctx, volumeMount.Type, teamID, volumeMount.ID)
+	var fs *chrooted.Chrooted
+	if volumeMount.VolumePath != "" {
+		// Use the persisted volume path directly, bypassing type lookup.
+		fs, err = h.builder.ChrootPath(ctx, volumeMount.VolumePath, volumeMount.ID)
+	} else {
+		// Fall back to building the path from volume type, team ID, and volume ID.
+		fs, err = h.builder.Chroot(ctx, volumeMount.Type, teamID, volumeMount.ID)
+	}
 	if err != nil {
 		return nil, fmt.Errorf("failed to mount %q: %w", volumeName, err)
 	}

packages/orchestrator/pkg/sandbox/sandbox.go

@@ -121,10 +121,11 @@ func (c *Config) GetNetworkIngress() *orchestrator.SandboxNetworkIngressConfig {
 }
 
 type VolumeMountConfig struct {
-	ID   uuid.UUID
-	Name string
-	Path string
-	Type string
+	ID         uuid.UUID
+	Name       string
+	Path       string
+	Type       string
+	VolumePath string
 }
 
 type EnvdMetadata struct {

packages/orchestrator/pkg/server/sandboxes.go

@@ -273,10 +273,11 @@ func createVolumeMountModelsFromAPI(volumeMounts []*orchestrator.SandboxVolumeMo
 		}
 
 		results = append(results, sandbox.VolumeMountConfig{
-			ID:   volumeID,
-			Name: v.GetName(),
-			Path: v.GetPath(),
-			Type: v.GetType(),
+			ID:         volumeID,
+			Name:       v.GetName(),
+			Path:       v.GetPath(),
+			Type:       v.GetType(),
+			VolumePath: v.GetVolumePath(),
 		})
 	}