Agent Sandboxes docs · Tasks
Volumes: a disk that outlives sandboxes
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.
CreateVolumemakes one of 1 to 1,000 GiB;CreateSandboxmounts 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.
volume = sandboxes.create_volume("data", size_gib=10)
print(volume.volume_id, volume.size_gib) # ziwv1r8ean3dd9sk 10
const volume = await sandboxes.createVolume({ name: "data", sizeGib: 10 });
console.log(volume.volumeId, volume.sizeGib);
volume, err := client.CreateVolume(ctx, &sandboxes.CreateVolumeRequest{Name: "data", SizeGib: 10})
if err != nil {
log.Fatal(err)
}
fmt.Println(volume.VolumeID, volume.SizeGib)
let volume = sandboxes
.create_volume(CreateVolumeRequest { name: "data".into(), size_gib: 10, ..Default::default() })
.await?;
println!("{} {}", volume.volume_id, volume.size_gib);
$ 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.
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")
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" });
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"})
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?;
$ 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'
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.
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)
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 });
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})
}
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?;
$ 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
NoCapacitymeanwhile. - 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_PRECONDITIONonDeleteVolume: a sandbox mounts it. Delete that sandbox first.RESOURCE_EXHAUSTEDwithLimitReached,volume_gib: the workspace's volumes would pass the plan's GiB. Delete one, or make it smaller.UNAVAILABLEwithNoCapacityon 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.