---
title: "Volumes: a disk that outlives sandboxes | Pethost Agent Sandboxes"
description: "Create a volume, mount it into sandboxes at a path, read-write by one or read-only by many, and know where it lives and what it costs."
---

[Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) · Tasks

# Volumes: a disk that outlives sandboxes

Updated 22 November 2026 · 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.

[PreviousFork a sandbox, memory and processes included](https://pethost.dev/docs/sandboxes/forks/) [NextSSH into a sandbox: shell, scp, SFTP and tunnels](https://pethost.dev/docs/sandboxes/ssh/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/templates/)
- [About](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Terms](https://pethost.dev/terms/)
- [Privacy](https://pethost.dev/privacy/)
- [Refunds](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Databases

- [Postgres](https://pethost.dev/postgres/)
- [Valkey](https://pethost.dev/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/sandboxes/)
- [Pricing](https://pethost.dev/sandboxes/#pricing)
- [Docs](https://pethost.dev/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparisons

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/blog/coolify-cloud-vs-dokploy-cloud/)
- [Railway vs Render vs Fly.io pricing](https://pethost.dev/blog/railway-vs-render-vs-fly-io-pricing/)
- [Managed Docker Compose hosting](https://pethost.dev/blog/managed-docker-compose-hosting/)

Alternatives

- [Railway alternatives](https://pethost.dev/blog/railway-alternatives/)
- [Heroku alternatives](https://pethost.dev/blog/heroku-alternatives/)
- [Dokploy alternatives](https://pethost.dev/blog/dokploy-alternatives/)
- [Coolify alternatives](https://pethost.dev/blog/coolify-alternatives/)
- [Render alternatives](https://pethost.dev/blog/render-alternatives/)
- [Sliplane alternatives](https://pethost.dev/blog/sliplane-alternatives/)
