How to Configure Persistent Volume Mounts for Sandboxes in OpenSandbox

To configure persistent volume mounts in OpenSandbox, define a Volume object specifying either a hostPath or pvc source and pass it to the Sandbox.create() method via the volumes parameter.

OpenSandbox provides flexible persistent storage capabilities that allow data to survive sandbox restarts and enable sharing between the host system and sandboxed workloads. This guide explains how to configure volume mounts using the OpenSandbox API and Python SDK, based on the implementation in the alibaba/OpenSandbox repository.

Volume Types Supported by OpenSandbox

OpenSandbox supports four distinct volume configurations defined in server/src/api/schema.py. Each type serves different persistence and isolation requirements.

Host-Path Volumes

Host-path volumes mount an existing directory from the machine running the sandbox daemon into the sandbox container. This is useful for development workflows where you need direct access to host filesystem data.

Volume(
    name="host-data",
    hostPath=HostPathVolumeSource(path="/absolute/host/dir"),
)

PVC (PersistentVolumeClaim) Volumes

PVC volumes integrate with Kubernetes PersistentVolumeClaims or Docker named volumes to provide durable storage that persists independently of the sandbox lifecycle. Use this for production workloads requiring data retention across sandbox restarts.

Volume(
    name="shared-storage",
    pvc=PVC(claimName="my-shared-pvc"),
)

PVC Sub-Path Volumes

PVC sub-path volumes mount only a specific subdirectory of a PersistentVolumeClaim. This configuration enables multiple sandboxes to share a single PVC while maintaining isolated views of the filesystem, as defined in the PersistentVolumeClaimVolumeSource model.

Volume(
    name="subdir",
    pvc=PVC(claimName="my-shared-pvc", subPath="user123"),
)

Read-Only Mounts

Any volume type can be mounted as read-only by setting the readOnly: true flag. This prevents the sandbox from writing to the mount point, applying ro permissions at the mount level for enhanced security.

API Schema and Volume Structure

The OpenSandbox REST API validates volume configurations against the Volume model defined in server/src/api/schema.py (line 159). The schema accepts three primary fields:

• hostPath – A HostPathVolumeSource object containing the absolute host directory path
• pvc – A PersistentVolumeClaimVolumeSource object with claimName and optional subPath
• readOnly – A boolean flag that enforces read-only access

The Python SDK mirrors this structure across two implementation layers: the high-level Volume class in sdks/sandbox/python/src/opensandbox/models/sandboxes.py (line 183) and the low-level API model in sdks/sandbox/python/src/opensandbox/api/lifecycle/models/volume.py (line 35).

Practical Implementation with Python SDK

The following examples demonstrate how to configure persistent volume mounts when creating sandboxes using the OpenSandbox Python SDK.

Mounting a Host Directory

from opensandbox import Sandbox, Volume, HostPathVolumeSource

sandbox_hw = Sandbox.create(
    image="python:3.10-slim",
    command=["sleep", "infinity"],
    volumes=[
        Volume(
            name="host-data",
            hostPath=HostPathVolumeSource(path="/opt/persistent-data"),
        )
    ],
)
print("Sandbox with host path mounted:", sandbox_hw.id)

Attaching a Read-Only PVC

from opensandbox import Sandbox, Volume, PVC

sandbox_pvc_ro = Sandbox.create(
    image="python:3.10-slim",
    command=["sleep", "infinity"],
    volumes=[
        Volume(
            name="shared-storage",
            pvc=PVC(claimName="my-shared-pvc"),
            readOnly=True,
        )
    ],
)
print("Sandbox with read-only PVC:", sandbox_pvc_ro.id)

Using PVC Sub-Path for Isolation

sandbox_sub = Sandbox.create(
    image="python:3.10-slim",
    command=["sleep", "infinity"],
    volumes=[
        Volume(
            name="subdir",
            pvc=PVC(claimName="my-shared-pvc", subPath="user123"),
        )
    ],
)
print("Sandbox with PVC sub-path:", sandbox_sub.id)

All arguments are serialized and sent to the OpenSandbox lifecycle API endpoint (POST /sandboxes). The SDK handles the translation from Python objects to the JSON payload expected by the server.

Verifying Mounts Inside the Sandbox

After creation, verify that volumes are accessible and respect their configured permissions:

# List contents of a host-path mount

out = sandbox_hw.commands.run(["ls", "-l", "/mnt/host-data"])
print(out.stdout)

# Attempt to write to a read-only PVC (this will fail)

result = sandbox_pvc_ro.commands.run(["touch", "/mnt/shared-storage/test.txt"])
print("Read-only protection active:", "Read-only file system" in result.stderr)

Lifecycle and Security Considerations

When configuring persistent volume mounts in OpenSandbox, observe these operational constraints defined in OSEP 0003:

1. Pre-provisioned Storage – The underlying storage (host directory or PVC) must exist before sandbox creation. OpenSandbox does not provision PVCs or create host directories automatically.

2. Data Persistence – Deleting a sandbox does not remove attached volumes. This intentional design preserves data across sandbox restarts, but requires manual cleanup of PVCs or host directories when no longer needed.

3. Host-Path Security – Mounting host paths exposes the host filesystem to the sandbox. Restrict this to trusted workloads or combine with the readOnly flag to minimize attack surface.

4. Kubernetes Integration – In Kubernetes deployments, the pvc field maps directly to cluster PersistentVolumeClaims. The sandbox daemon mounts the bound claim into the container hosting the sandbox process.

Summary

• OpenSandbox supports host-path, PVC, and PVC sub-path volumes with optional read-only restrictions.
• Define volumes using the Volume model in server/src/api/schema.py, implemented in the Python SDK at sdks/sandbox/python/src/opensandbox/models/sandboxes.py.
• Pass volume configurations to Sandbox.create() via the volumes parameter list.
• Ensure backing storage exists before sandbox creation; OpenSandbox never provisions storage automatically.
• Volumes persist after sandbox deletion and require explicit cleanup to free storage resources.

Frequently Asked Questions

Can OpenSandbox automatically create a PVC for my sandbox?

No. According to the OSEP 0003 specification and implementation in server/src/api/schema.py, OpenSandbox expects the PersistentVolumeClaim (or host directory) to exist prior to sandbox creation. You must provision the PVC through Kubernetes or create the host directory manually before referencing it in the volume configuration.

What happens to my data when I delete a sandbox?

The volume data persists. OpenSandbox intentionally decouples volume lifecycle from sandbox lifecycle to ensure data survives restarts. When you delete a sandbox via the API, the attached volumes remain intact. You must explicitly delete the PVC or clean the host directory to reclaim storage space.

How do I share storage between multiple sandboxes safely?

Use a PVC sub-path volume. Configure multiple sandboxes to mount different subPath values within the same claimName. Each sandbox sees only its isolated subdirectory while sharing the underlying storage resource. This pattern is documented in sdks/sandbox/python/src/opensandbox/api/lifecycle/models/volume.py.

Are host-path volumes secure for production use?

Host-path volumes require careful security consideration. Because they expose host filesystem paths directly to the sandbox, Alibaba recommends using them only for trusted development workloads or marking them readOnly: true. For production isolation, prefer PVC volumes backed by Kubernetes storage classes that enforce proper access controls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}