Docs do Agent Sandboxes · Tarefas
Volumes: um disco que sobrevive aos sandboxes
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.
CreateVolumecria um de 1 a 1.000 GiB;CreateSandboxmonta 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.
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: 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.
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: 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.
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
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_PRECONDITIONemDeleteVolume: um sandbox o monta. Exclua esse sandbox antes.RESOURCE_EXHAUSTEDcomLimitReached,volume_gib: os volumes do espaço de trabalho passariam dos GiB do plano. Exclua um, ou crie-o menor.UNAVAILABLEcomNoCapacityem 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.