# How to Configure Persistent Volume Mounts for Sandboxes in OpenSandbox

> Learn to configure persistent volume mounts for sandboxes in OpenSandbox. Easily define hostPath or pvc sources and pass them to the Sandbox.create() method for seamless data persistence.

- Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/alibaba/OpenSandbox/blob/main/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.

```python
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.

```python
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.

```python
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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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

```python
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

```python
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

```python
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:

```python

# 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`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/api/schema.py), implemented in the Python SDK at [`sdks/sandbox/python/src/opensandbox/models/sandboxes.py`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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.