---
title: "Volumes: um disco que sobrevive aos sandboxes | Pethost Agent Sandboxes"
description: "Crie um volume, monte-o em sandboxes em um caminho, com leitura e escrita por um ou só leitura por muitos, e saiba onde ele fica e quanto custa."
---

[Docs do Agent Sandboxes](https://pethost.dev/pt/docs/sandboxes/) · Tarefas

# Volumes: um disco que sobrevive aos sandboxes

Atualizado em 22 de novembro de 2026 · 6 min de leitura

Um volume é um disco fora de todo sandbox, montado em um deles em um caminho: um dataset que muitos sandboxes leem, um cache que sobrevive a cada job, arquivos que um sandbox excluído deve deixar para trás. Ele fica no disco de um servidor, e é isso que você precisa saber antes de colocar qualquer coisa nele.

**Em resumo**

- **`CreateVolume`** cria um de 1 a 1.000 GiB; `CreateSandbox` monta até 4 na criação, cada um em um caminho.
- **Leitura e escrita por um sandbox de cada vez,** só leitura por qualquer número deles.
- **Em um servidor,** sem cópia: um sandbox que o monta roda ali, e se esse servidor for perdido, o volume também será.
- **Cobrado pelo tamanho inteiro,** US$ 0,20 por GiB ao mês, usado ou não.

### Step 1: Crie um volume

Um volume é criado vazio, em um servidor com espaço, e a raiz dele pertence a `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: Monte-o em um sandbox

As montagens são dadas na criação, cada uma um volume e um caminho absoluto. O sandbox roda no servidor do volume.

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: Compartilhe-o só para leitura e exclua-o quando terminar

Quando nenhum sandbox o monta em leitura e escrita, qualquer número pode montá-lo só para leitura. Um volume fica quando os sandboxes que o montaram são excluídos, e só vai embora por `DeleteVolume`, que é recusado enquanto um sandbox o monta.

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

## Onde um volume fica

Um volume é um arquivo no disco de um servidor de sandboxes, com um sistema de arquivos ext4, e um sandbox que o monta roda nesse servidor. Ele não é copiado para o armazenamento de objetos nem para outro servidor. Isso tem três efeitos:

- **Se o servidor for perdido, o volume também será:** ele vira DELETED, e os sandboxes que o montavam o perdem. Não guarde ali a única cópia de nada: envie também o que importa para um armazenamento seu.
- **Um sandbox com volume fica no servidor dele.** Um sandbox parado sem volumes pode iniciar em outro servidor quando o seu está cheio; um com volume espera por espaço no seu, e enquanto isso é recusado com `NoCapacity`.
- **Um sandbox com um volume de leitura e escrita não pode ter fork:** um volume é gravado por um sandbox de cada vez.

Um volume divide a velocidade de disco do sandbox que o monta, 64 MiB/s por vCPU. Um maior que metade do disco de um servidor é recusado.

## Volumes e o disco do próprio sandbox

A maior parte do trabalho não precisa de volume. O disco do próprio sandbox sobrevive às pausas e paradas dele: o disco de um sandbox parado fica guardado no armazenamento de objetos e volta quando ele é retomado, em qualquer servidor. Um template leva arquivos para todo sandbox novo. Um volume serve para dados que sobrevivem aos sandboxes que os usam, ou que muitos leem ao mesmo tempo: um dataset, os pesos de um modelo, um cache compartilhado.

## Quanto custa

Um volume conta o tamanho inteiro, US$ 0,20 por GiB ao mês, por segundo, da criação até a exclusão, montado ou não por um sandbox. O seu plano limita o que os volumes do espaço de trabalho ocupam juntos: 100 GiB no plano de US$ 20, 600 GiB no plano de US$ 100, 10 GiB no teste grátis. `Workspace.volume_gib_used` diz o que eles ocupam agora.

## Quando não funciona

- **`FAILED_PRECONDITION`, o volume está montado por outro sandbox:** ele está montado em leitura e escrita. Monte-o só para leitura, ou exclua ou pare o sandbox que grava nele.
- **`FAILED_PRECONDITION`, o journal dele pode precisar ser reaplicado:** o último sandbox que gravou nele terminou antes de desmontá-lo. Monte-o em leitura e escrita uma vez, depois só para leitura de novo.
- **`FAILED_PRECONDITION` em `DeleteVolume`:** um sandbox o monta. Exclua esse sandbox antes.
- **`RESOURCE_EXHAUSTED` com `LimitReached`, `volume_gib`:** os volumes do espaço de trabalho passariam dos GiB do plano. Exclua um, ou crie-o menor.
- **`UNAVAILABLE` com `NoCapacity` em uma criação ou retomada:** o servidor do volume não tem espaço agora, e um sandbox com volume não pode ir para outro lugar. Tente de novo mais tarde.

## Perguntas

### Um volume tem backup?

Não. Ele fica no disco de um servidor e não é copiado para lugar nenhum: guarde em outro lugar uma cópia do que importa.

### Vários sandboxes podem compartilhar um volume?

Só para leitura, qualquer número ao mesmo tempo. Com leitura e escrita, um de cada vez.

### Posso montar um volume em um sandbox rodando?

Não: as montagens são dadas na criação, até 4 por sandbox.

### Um volume é cobrado enquanto nada o monta?

Sim, pelo tamanho inteiro, US$ 0,20 por GiB ao mês, até você excluí-lo.

### Preciso de um volume para guardar arquivos entre sessões?

Não. O disco do próprio sandbox sobrevive a pausas e paradas; um volume serve para dados que sobrevivem ao sandbox.

[AnteriorFaça fork de um sandbox, com memória e processos](https://pethost.dev/pt/docs/sandboxes/forks/) [PróximaSSH em um sandbox: shell, scp, SFTP e túneis](https://pethost.dev/pt/docs/sandboxes/ssh/)

## Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

[Começar o teste grátis](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/pt/templates/)
- [Sobre nós](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/pt/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Termos](https://pethost.dev/terms/)
- [Privacidade](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bancos de dados

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

Agent Sandboxes

- [Sandboxes](https://pethost.dev/pt/sandboxes/)
- [Preços](https://pethost.dev/pt/sandboxes/#pricing)
- [Docs](https://pethost.dev/pt/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparativos

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

Alternativas

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