Python Sandbox SDK volumes

Volumes provide persistent storage that can be mounted into Porter Sandboxes. Create a volume before launching the sandbox, then pass the volume ID in volume_mounts.

Sandboxes are in a private beta. Please reach out to us at support@porter.run or over Slack if you are interested in joining.

Create and mount a volume

from porter_sandbox import Porter

with Porter() as porter:
    volume = porter.volumes.create(name="agent-workspace")

    sandbox = porter.sandboxes.create(
        image="python:3.12-slim",
        volume_mounts={"/workspace": volume.id},
    )

    try:
        sandbox.exec(["python", "-c", "open('/workspace/result.txt', 'w').write('done')"])
        result = sandbox.exec(["cat", "/workspace/result.txt"])
        print(result.stdout)
    finally:
        sandbox.terminate()

volume_mounts is a dictionary keyed by the absolute mount path inside the sandbox. Each value is a volume ID.

List volumes

list() returns volume handles:

with Porter() as porter:
    for volume in porter.volumes.list():
        print(volume.id, volume.name, volume.phase, volume.attached_to, volume.path)

Get a volume by name

Volume names are unique within the cluster. Use get(name) when you know a volume name:

with Porter() as porter:
    volume = porter.volumes.get("agent-workspace")
    print(volume.id)

Volume names may contain lowercase letters, numbers, and hyphens, and must start and end with a letter or number. A volume name must be unique within the cluster for the lifetime of the volume. After the volume is deleted, the name can be used again.

Inspect a volume

with Porter() as porter:
    volume = porter.volumes.get("agent-workspace")
    print(volume.name, volume.phase, volume.attached_to, volume.created_at)

Browse volume contents

listdir returns the entries directly inside a directory, directories first:

with Porter() as porter:
    volume = porter.volumes.get("agent-workspace")

    for file in volume.listdir("/checkpoints"):
        print(file.path, "dir" if file.is_directory else file.size_bytes)

iterdir walks the whole tree instead, descending into every subdirectory:

for file in volume.iterdir("/checkpoints"):
    print(file.path, file.size_bytes)

search walks the tree and returns only the entries whose name contains a substring, optionally rooted at a subdirectory:

configs = volume.search("config.json")
checkpoint_configs = volume.search("config.json", path="/checkpoints")

Read a file

read_text returns a whole file as a string, and read_file returns raw bytes:

config = volume.read_text("/checkpoints/config.json")
data = volume.read_file("/checkpoints/weights.bin")

Both accept offset and length to read part of a file:

head = volume.read_text("/logs/train.log", offset=0, length=512)

For files too large to hold in memory, stream pages through the file in chunks (8 MiB by default):

with open("model.safetensors", "wb") as out:
    for chunk in volume.stream("/checkpoints/model.safetensors"):
        out.write(chunk)

Reading a path that does not exist raises NotFoundError. Every method here has an async counterpart on AsyncVolume, returned by AsyncPorter:

async with AsyncPorter() as porter:
    volume = await porter.volumes.get("agent-workspace")

    async for file in volume.iterdir("/checkpoints"):
        print(file.path)

    config = await volume.read_text("/checkpoints/config.json")

Access volume data from apps

Volumes live on a shared disk that apps on the same cluster can attach. Attach the disk named sandbox-volumes to a service in your app; it mounts at /data/<app-name>/sandbox-volumes and contains one subdirectory per volume. Each volume handle exposes a path with the volume’s subdirectory on that disk, so an app reads a volume’s data at /data/<app-name>/sandbox-volumes/<path>:

with Porter() as porter:
    volume = porter.volumes.get("agent-workspace")
    print(volume.path)  # sandbox-vol-2f1c8b7e-...

The disk is a live view: writes a sandbox makes to its mounted volume are visible to apps right away, and new volumes show up as new subdirectories without redeploying the app.

Volume contents are written by sandboxed workloads, which are often running untrusted code. Treat anything your app reads from this disk as untrusted input: hostile file contents, names, or sizes can exploit vulnerabilities in the code that processes them. Porter isolates the sandboxes themselves but does not inspect or sanitize what they write, so validating this data before acting on it is your application’s responsibility.

Delete a volume

Delete volumes by name:

with Porter() as porter:
    porter.volumes.delete("agent-workspace")

Deleting a volume fails while it is attached to a sandbox. Terminate any attached sandboxes before deleting the volume.

Async usage

from porter_sandbox import AsyncPorter

async with AsyncPorter() as porter:
    volume = await porter.volumes.create(name="async-workspace")

    sandbox = await porter.sandboxes.create(
        image="python:3.12-slim",
        volume_mounts={"/workspace": volume.id},
    )

    try:
        result = await sandbox.exec(["sh", "-lc", "echo hello > /workspace/out.txt && cat /workspace/out.txt"])
        print(result.stdout)
    finally:
        await sandbox.terminate()

Documentation

Python Sandbox SDK volumes

Create and mount a volume

List volumes

Get a volume by name

Inspect a volume

Browse volume contents

Read a file

Access volume data from apps

Delete a volume

Async usage

Next steps

​Create and mount a volume

​List volumes

​Get a volume by name

​Inspect a volume

​Browse volume contents

​Read a file

​Access volume data from apps

​Delete a volume

​Async usage

​Next steps

Create and mount a volume

List volumes

Get a volume by name

Inspect a volume

Browse volume contents

Read a file

Access volume data from apps

Delete a volume

Async usage

Next steps