English
Docs menu

Agent Sandboxes docs · Tasks

Volumes: a disk that outlives sandboxes

Updated · 6 min read

A volume is a disk outside every sandbox, mounted into one at a path: a dataset many sandboxes read, a cache that outlives each job, files a sandbox you delete should leave behind. It lives on one server's disk, which is what you need to know before you put anything on it.

In short
  • CreateVolume makes one of 1 to 1,000 GiB; CreateSandbox mounts up to 4 at create, each at a path.
  • Read-write by one sandbox at a time, read-only by any number.
  • On one server, not copied: a sandbox that mounts it runs there, and if that server is lost, so is the volume.
  • Billed by its whole size, $0.20 a GiB a month, used or not.

Step 1: Create a volume

A volume is made empty, on a server with room, and its root belongs to user.

Python
volume = sandboxes.create_volume("data", size_gib=10)
print(volume.volume_id, volume.size_gib)  # ziwv1r8ean3dd9sk 10
TypeScript
const volume = await sandboxes.createVolume({ name: "data", sizeGib: 10 });
console.log(volume.volumeId, volume.sizeGib);
Go
volume, err := client.CreateVolume(ctx, &sandboxes.CreateVolumeRequest{Name: "data", SizeGib: 10})
if err != nil {
	log.Fatal(err)
}
fmt.Println(volume.VolumeID, volume.SizeGib)
Rust
let volume = sandboxes
    .create_volume(CreateVolumeRequest { name: "data".into(), size_gib: 10, ..Default::default() })
    .await?;
println!("{} {}", volume.volume_id, volume.size_gib);
CLI
$ pethost sandbox volume new data --size 10
✓ Made the volume data, 10 GiB. Mount it:  pethost sandbox new --mount o2rvhgm1dxaefoj7:/data
o2rvhgm1dxaefoj7

Step 2: Mount it into a sandbox

Mounts are given at create, each a volume and an absolute path. The sandbox runs on the volume's server.

Python
from pethost.sandboxes import Mount

writer = sandboxes.create_sandbox("base", mounts=[Mount(volume_id=volume.volume_id, path="/data")])
sandboxes.run_command(writer.sandbox_id, command="date > /data/first-run.txt")
TypeScript
const writer = await sandboxes.createSandbox({
  template: "base",
  mounts: [{ volumeId: volume.volumeId, path: "/data" }],
});
await sandboxes.runCommand({ sandboxId: writer.sandboxId, command: "date > /data/first-run.txt" });
Go
writer, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template: "base",
	Mounts:   []sandboxes.Mount{{VolumeID: volume.VolumeID, Path: "/data"}},
})
if err != nil {
	log.Fatal(err)
}
_, err = client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: writer.SandboxID, Command: "date > /data/first-run.txt"})
Rust
let mount = Mount { volume_id: volume.volume_id.clone(), path: "/data".into(), ..Default::default() };
let writer = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "base".into(), mounts: vec![mount], ..Default::default() })
    .await?;
sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: writer.sandbox_id.clone(),
        command: "date > /data/first-run.txt".into(),
        ..Default::default()
    })
    .await?;
CLI
$ pethost sandbox new --name writer --mount o2rvhgm1dxaefoj7:/data
✓ Made sandbox writer (upc3ehxd65rjgz32): default, running, from base@17, in <1 s
upc3ehxd65rjgz32
Next:   pethost sandbox run upc3ehxd65rjgz32 -- <command>   ·   pethost sandbox shell upc3ehxd65rjgz32
$ pethost sandbox run writer -- 'date > /data/first-run.txt'
MCP
CreateSandbox {"name": "writer", "mounts": [{"volume_id": "…", "path": "/data"}]}

Step 3: Share it read-only, and delete it when done

Once no sandbox mounts it read-write, any number may mount it read-only. A volume stays when the sandboxes that mounted it are deleted, and goes only by DeleteVolume, which is refused while a sandbox mounts it.

Python
sandboxes.delete_sandbox(writer.sandbox_id)
reader = sandboxes.create_sandbox("base", mounts=[Mount(volume_id=volume.volume_id, path="/data", read_only=True)])
print(sandboxes.run_command(reader.sandbox_id, command="cat /data/first-run.txt").stdout)  # Sun Nov 22 00:25:33 UTC 2026
sandboxes.delete_sandbox(reader.sandbox_id)
sandboxes.delete_volume(volume.volume_id)
TypeScript
await sandboxes.deleteSandbox({ sandboxId: writer.sandboxId });
const reader = await sandboxes.createSandbox({
  template: "base",
  mounts: [{ volumeId: volume.volumeId, path: "/data", readOnly: true }],
});
console.log((await sandboxes.runCommand({ sandboxId: reader.sandboxId, command: "cat /data/first-run.txt" })).stdout);
await sandboxes.deleteSandbox({ sandboxId: reader.sandboxId });
await sandboxes.deleteVolume({ volumeId: volume.volumeId });
Go
if _, err := client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: writer.SandboxID}); err != nil {
	log.Fatal(err)
}
reader, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template: "base",
	Mounts:   []sandboxes.Mount{{VolumeID: volume.VolumeID, Path: "/data", ReadOnly: true}},
})
if err != nil {
	log.Fatal(err)
}
read, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: reader.SandboxID, Command: "cat /data/first-run.txt"})
if err != nil {
	log.Fatal(err)
}
fmt.Print(read.Stdout)
_, err = client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: reader.SandboxID})
if err == nil {
	_, err = client.DeleteVolume(ctx, &sandboxes.DeleteVolumeRequest{VolumeID: volume.VolumeID})
}
Rust
sandboxes
    .delete_sandbox(DeleteSandboxRequest { sandbox_id: writer.sandbox_id.clone(), ..Default::default() })
    .await?;
let mount = Mount { volume_id: volume.volume_id.clone(), path: "/data".into(), read_only: true };
let reader = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "base".into(), mounts: vec![mount], ..Default::default() })
    .await?;
let read = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: reader.sandbox_id.clone(),
        command: "cat /data/first-run.txt".into(),
        ..Default::default()
    })
    .await?;
print!("{}", read.stdout);
sandboxes
    .delete_sandbox(DeleteSandboxRequest { sandbox_id: reader.sandbox_id.clone(), ..Default::default() })
    .await?;
sandboxes
    .delete_volume(DeleteVolumeRequest { volume_id: volume.volume_id.clone(), ..Default::default() })
    .await?;
CLI
$ pethost sandbox rm writer --yes
upc3ehxd65rjgz32   deleted
$ pethost sandbox new --name reader --mount o2rvhgm1dxaefoj7:/data:ro
✓ Made sandbox reader (zc44605gliwn2v1b): default, running, from base@17, in <1 s
zc44605gliwn2v1b
Next:   pethost sandbox run zc44605gliwn2v1b -- <command>   ·   pethost sandbox shell zc44605gliwn2v1b
$ pethost sandbox run reader -- cat /data/first-run.txt
Sun Nov 22 00:25:40 UTC 2026
$ pethost sandbox rm reader --yes
zc44605gliwn2v1b   deleted
$ pethost sandbox volume rm o2rvhgm1dxaefoj7 --yes
o2rvhgm1dxaefoj7

Where a volume lives

A volume is a file on one sandbox server's disk, holding an ext4 filesystem, and a sandbox that mounts it runs on that server. It is not copied to object storage or to another server. That has three effects:

  • If its server is lost, the volume is lost: it becomes DELETED, and the sandboxes that mounted it lose it. Keep the only copy of nothing there: push what matters to a store of your own as well.
  • A sandbox with a volume stays on its server. A stopped sandbox without volumes may start on another server when its own is full; one with a volume waits for room on its own, and is refused with NoCapacity meanwhile.
  • A sandbox with a read-write volume cannot be forked: a volume is written by one sandbox at a time.

A volume shares the disk speed of the sandbox that mounts it, 64 MiB/s a vCPU. One larger than half a server's disk is refused.

Volumes and a sandbox's own disk

Most work needs no volume. A sandbox's own disk survives its pauses and stops: a stopped sandbox's disk is kept in object storage, and comes back when it resumes, on any server. A template carries files to every new sandbox. A volume is for data that outlives the sandboxes that use it, or that many read at once: a dataset, a model's weights, a shared cache.

What it costs

A volume counts its whole size, $0.20 a GiB a month, by the second, from its create to its delete, whether a sandbox mounts it or not. Your plan bounds what the workspace's volumes take together: 100 GiB on the $20 plan, 600 GiB on the $100 plan, 10 GiB in the trial. Workspace.volume_gib_used says what they take now.

When it does not work

  • FAILED_PRECONDITION, the volume is mounted by another sandbox: it is mounted read-write. Mount it read-only, or delete or stop the sandbox that writes it.
  • FAILED_PRECONDITION, its journal may need replaying: the last sandbox that wrote it ended before it unmounted. Mount it read-write once, then read-only again.
  • FAILED_PRECONDITION on DeleteVolume: a sandbox mounts it. Delete that sandbox first.
  • RESOURCE_EXHAUSTED with LimitReached, volume_gib: the workspace's volumes would pass the plan's GiB. Delete one, or make it smaller.
  • UNAVAILABLE with NoCapacity on a create or resume: the volume's server has no room now, and a sandbox with a volume cannot go elsewhere. Try again later.

Questions

Is a volume backed up?

No. It lives on one server's disk and is not copied anywhere: keep a copy of what matters elsewhere.

Can several sandboxes share a volume?

Read-only, any number at once. Read-write, one at a time.

Can I mount a volume into a running sandbox?

No: mounts are given at create, up to 4 a sandbox.

Is a volume billed while nothing mounts it?

Yes, by its whole size, $0.20 a GiB a month, until you delete it.

Do I need a volume to keep files between sessions?

No. A sandbox's own disk survives pauses and stops; a volume is for data that outlives the sandbox.

Try Pethost Agent Sandboxes

A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.

Start the trial