Português
Menu da documentação

Docs do Agent Sandboxes · Tarefas

Volumes: um disco que sobrevive aos sandboxes

Atualizado em · 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.

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