TypeScript 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.

Create and mount a volume

import { Porter } from "porter-sandbox";

const porter = new Porter();

const volume = await porter.volumes.create({
  name: "agent-workspace",
});

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

try {
  await sandbox.exec(["python", "-c", "open('/workspace/result.txt', 'w').write('done')"]);
  const result = await sandbox.exec(["cat", "/workspace/result.txt"]);
  console.log(result.stdout);
} finally {
  await sandbox.terminate();
  porter.close();
}

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

Object volumes

Passing type and object to create makes an object volume, which exposes a registered S3 bucket. It mounts like any other volume through volume_mounts.

const datasets = await porter.volumes.create({
  name: "datasets",
  type: "object",
  object: { bucket: "my-bucket", prefix: "training/v1", access: "read_only" },
});

Object volumes get their own ObjectVolume handle. It carries the shared surface — id, name, type, phase, attachedTo, createdAt, refresh, and delete — plus the object spec, and none of the file methods: an object volume’s contents live in its bucket. create, get, and list return Volume | ObjectVolume, and the type getter discriminates the union, so a check narrows it (instanceof ObjectVolume works too):

for (const volume of await porter.volumes.list()) {
  if (volume.type === "object") {
    console.log(volume.name, "exposes bucket", volume.object.bucket);
  } else {
    const checkpoints = await volume.listdir("/checkpoints");
  }
}

File system mode

Set mode to "filesystem" to mount the bucket in file system mode, which supports renames and in-place edits. The bucket needs the sandbox_filesystem capability.

const workspace = await porter.volumes.create({
  name: "team-a-workspace",
  type: "object",
  object: { bucket: "my-bucket", prefix: "team-a", mode: "filesystem" },
});

The volume still returns an ObjectVolume handle, so manage its files from a sandbox that mounts it or through S3.

List volumes

list() returns volume handles:

import { Porter } from "porter-sandbox";

const porter = new Porter();

for (const volume of await porter.volumes.list()) {
  console.log(volume.id, volume.name, volume.phase, volume.attachedTo, volume.path);
}

porter.close();

Get a volume by name

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

import { Porter } from "porter-sandbox";

const porter = new Porter();
const volume = await porter.volumes.get("agent-workspace");

console.log(volume.id);

porter.close();

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

import { Porter } from "porter-sandbox";

const porter = new Porter();
const volume = await porter.volumes.get("agent-workspace");

console.log(volume.name, volume.phase, volume.attachedTo, volume.createdAt);
porter.close();

Browse volume contents

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

import { Porter } from "porter-sandbox";

const porter = new Porter();
const volume = await porter.volumes.get("agent-workspace");

for (const file of await volume.listdir("/checkpoints")) {
  console.log(file.path, file.isDirectory ? "dir" : file.sizeBytes);
}

porter.close();

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

for await (const file of volume.iterdir("/checkpoints")) {
  console.log(file.path, file.sizeBytes);
}

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

const configs = await volume.search("config.json");
const checkpointConfigs = await volume.search("config.json", { path: "/checkpoints" });

Read a file

readText returns a whole file as a string, and readFile returns raw bytes:

const config = await volume.readText("/checkpoints/config.json");
const bytes = await volume.readFile("/checkpoints/weights.bin");

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

const head = await volume.readText("/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):

import { createWriteStream } from "node:fs";

const out = createWriteStream("model.safetensors");
for await (const chunk of volume.stream("/checkpoints/model.safetensors")) {
  out.write(chunk);
}
out.end();

Reading a path that does not exist throws NotFoundError.

Write a file

writeText writes a string and writeFile writes raw bytes. Both create parent directories as needed and replace any existing file at the path:

await volume.writeText("/config/app.yaml", "replicas: 3\n");
await volume.writeFile("/checkpoints/weights.bin", bytes);

A write is atomic: the file appears at its path only after the last byte lands, so an interrupted or failed write leaves the previous contents in place rather than a truncated file. An uploaded file gets the same permissions a sandbox writing to its own mount would leave, so it is indistinguishable from a file the sandbox wrote. You can write to a volume whether or not a sandbox has it mounted; the volume itself is the target. A single write is capped at 1 GiB; a request made from outside the cluster with an API token must also finish within 30 seconds, so write very large files from an app running in the same cluster.

Move or rename a file

moveFile moves a file or directory to a new path. The second argument is the entry’s full new path, not a directory to drop it into, so one call both renames and relocates. A directory moves with everything under it:

await volume.moveFile("/notes.txt", "/archive/notes.txt");
await volume.moveFile("/models/v1", "/models/v2");

The destination’s parent directory must already exist, and nothing is overwritten. Moving onto a path something already occupies fails and leaves the entry where it was.

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

import { Porter } from "porter-sandbox";

const porter = new Porter();
const volume = await porter.volumes.get("agent-workspace");

console.log(volume.path); // sandbox-vol-2f1c8b7e-...
porter.close();

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:

import { Porter } from "porter-sandbox";

const porter = new Porter();

await porter.volumes.delete("agent-workspace");
porter.close();

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

Documentation

TypeScript Sandbox SDK volumes

Create and mount a volume

Object volumes

File system mode

List volumes

Get a volume by name

Inspect a volume

Browse volume contents

Read a file

Write a file

Move or rename a file

Access volume data from apps

Delete a volume

Next steps

​Create and mount a volume

​Object volumes

​File system mode

​List volumes

​Get a volume by name

​Inspect a volume

​Browse volume contents

​Read a file

​Write a file

​Move or rename a file

​Access volume data from apps

​Delete a volume

​Next steps

Create and mount a volume

Object volumes

File system mode

List volumes

Get a volume by name

Inspect a volume

Browse volume contents

Read a file

Write a file

Move or rename a file

Access volume data from apps

Delete a volume

Next steps