TypeScript Sandbox SDK volumes

Create, mount, list, and delete sandbox volumes with the TypeScript Sandbox SDK

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 [e-mail] or over Slack if you are interested in joining.

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.

List volumes

import { Porter } from "porter-sandbox";

const porter = new Porter();
const response = await porter.volumes.list();

for (const volume of response.volumes) {
  console.log(volume.id, volume.name, volume.phase, volume.attached_to);
}

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.attached_to);
porter.close();

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.

Next steps

• TypeScript Sandbox SDK quickstart
• TypeScript Sandbox SDK reference
• TypeScript Sandbox SDK errors