Docs do Agent Sandboxes · Tarefas
Templates: inicie sandboxes prontos para trabalhar
Um template é aquilo de onde um sandbox inicia. O nosso, base, tem as ferramentas; o seu é o disco de um sandbox salvo como está, com os pacotes que você instalou, o seu código e as imagens Docker dele. Um sandbox feito a partir dele inicia em cerca de 0,22 s sem nada mais para instalar.
CreateTemplatesalva o disco e as configurações de um sandbox como uma nova versão,my-app@1,my-app@2, enquanto o sandbox continua rodando.- SAVING, depois READY em cerca de 1,5 s para um pequeno, e cerca de 10 s por GiB do que ele guarda de próprio.
CreateSandboxcom"my-app"inicia da versão READY mais recente, em qualquer servidor.- Só arquivos: um template não guarda memória, processos nem conversas de agentes. Ele não é cobrado; o seu plano limita o tamanho.
Step 1: Prepare um sandbox
Crie um sandbox a partir do base e configure-o como todo sandbox novo deveria ser: clone o seu código, instale as dependências, baixe as imagens Docker que ele roda, aqueça os caches (comandos e arquivos). As configurações também contam: o template leva o ciclo de vida, a saída, as portas públicas e o ambiente do sandbox como estão agora, e os sandboxes feitos a partir dele iniciam com eles, a não ser que a criação diga outra coisa.
Step 2: Salve-o como template
CreateTemplate responde com a nova versão SAVING em milissegundos, assim que guarda o disco como está: o sandbox continua rodando. O servidor então reduz a versão ao que ela guarda e a envia. Espere por READY antes de iniciar a partir dessa versão.
import time
from pethost.sandboxes import TemplateState
version = sandboxes.create_template("my-app", sandbox_id=sandbox_id, description="Node 22 and our dependencies")
while version.state == TemplateState.SAVING:
time.sleep(1)
version = sandboxes.get_template(f"my-app@{version.version}")
print(version.name, version.version, version.state.name, version.min_size.name, version.size_bytes)
# my-app 1 READY SMALL 25447048
let version = await sandboxes.createTemplate({
name: "my-app",
sandboxId,
description: "Node 22 and our dependencies",
});
while (version.state === TemplateState.SAVING) {
await new Promise((resolve) => setTimeout(resolve, 1000));
version = await sandboxes.getTemplate({ template: `my-app@${version.version}` });
}
console.log(version.name, version.version, version.state, version.minSize, version.sizeBytes);
version, err := client.CreateTemplate(ctx, &sandboxes.CreateTemplateRequest{
Name: "my-app",
SandboxID: id,
Description: "Node 22 and our dependencies",
})
for err == nil && version.State == sandboxes.TemplateStateSaving {
time.Sleep(time.Second)
version, err = client.GetTemplate(ctx, &sandboxes.GetTemplateRequest{Template: fmt.Sprintf("my-app@%d", version.Version)})
}
if err != nil {
log.Fatal(err)
}
fmt.Println(version.Name, version.Version, version.State, version.MinSize, version.SizeBytes)
let mut version = sandboxes
.create_template(CreateTemplateRequest {
name: "my-app".into(),
sandbox_id: id.clone(),
description: "Node 22 and our dependencies".into(),
..Default::default()
})
.await?;
while matches!(version.state, TemplateState::Saving) {
tokio::time::sleep(std::time::Duration::from_secs(1)).await;
let template = format!("my-app@{}", version.version);
version = sandboxes.get_template(GetTemplateRequest { template, ..Default::default() }).await?;
}
println!("{} {} {:?} {:?} {}", version.name, version.version, version.state, version.min_size, version.size_bytes);
$ pethost sandbox template save api-dev my-app --description 'Node 22 and our dependencies'
✓ Saving my-app@2: it is ready once uploaded. See: pethost sandbox template show my-app@2
my-app@2
$ pethost sandbox template ls my-app
my-app@2 ready 68 MB 55 s ago Node 22 and our dependencies
my-app@1 ready 24 MB 1 min ago Node 22 and our dependencies
CreateTemplate {"name": "my-app", "sandbox_id": "…", "description": "Node 22 and our dependencies"}
ListTemplates {"name": "my-app"}
Step 3: Inicie sandboxes a partir dele
Nomeie o template em CreateSandbox: "my-app" é a versão READY mais recente, "my-app@2" exatamente aquela. O primeiro sandbox de uma versão em um servidor a busca, a cerca de 10 s por GiB; o servidor a guarda, e os seguintes iniciam em cerca de 0,22 s.
preview = sandboxes.create_sandbox("my-app")
print(preview.sandbox_id, preview.template) # 8j37xshusqwdz8cs my-app@1
const preview = await sandboxes.createSandbox({ template: "my-app" });
console.log(preview.sandboxId, preview.template);
preview, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "my-app"})
if err != nil {
log.Fatal(err)
}
fmt.Println(preview.SandboxID, preview.Template)
let preview = sandboxes
.create_sandbox(CreateSandboxRequest { template: "my-app".into(), ..Default::default() })
.await?;
println!("{} {}", preview.sandbox_id, preview.template);
$ pethost sandbox new --template my-app
✓ Made sandbox ofvm8by6buvd4rkd: default, running, from my-app@2, in <1 s
port 5173: https://5173-ofvm8by6buvd4rkd.sbx1.sandboxes.pethost.network
ofvm8by6buvd4rkd
Next: pethost sandbox run ofvm8by6buvd4rkd -- <command> · pethost sandbox shell ofvm8by6buvd4rkd
CreateSandbox {"template": "my-app"}
O template da resposta nomeia a versão exata de onde ele iniciou, como my-app@1.
O que um template guarda
- Guardado: todo arquivo do disco do sandbox, os pacotes, o seu código, as imagens e os containers do Docker entre eles; e as configurações do sandbox, com as quais os sandboxes dele iniciam, a não ser que a criação diga outra coisa.
- Não guardado: memória e processos, então um sandbox de um template inicia sem nada do que rodava; o histórico de comandos e as conversas dos agentes de código, sem os quais os sandboxes dele iniciam.
- Novo em cada sandbox: id, hostname, machine-id e aleatoriedade do kernel próprios.
Para copiar um sandbox com a memória e os processos, como ele está neste segundo, faça um fork dele: forks. Um template serve para muitos sandboxes ao longo de dias; um fork, para algumas cópias agora.
Versões e tamanhos
Cada salvamento de um nome é a próxima versão dele. "my-app" sempre quer dizer a versão READY mais recente, a anterior enquanto uma nova é salva, então salvar nunca quebra as suas criações. Um nome guarda 10 versões; uma versão FAILED não ocupa nada e some um dia depois. Um espaço de trabalho salva uma versão de cada vez, e um sandbox mantém a versão de onde iniciou, mesmo depois que você exclui o template.
Uma versão READY tem um min_size: o menor tamanho cujo disco comporta o que ela salvou. Os sandboxes dela aceitam qualquer tamanho a partir dele. Uma criação com um tamanho menor é recusada, nomeando o que cabe.
Onde fica guardado, e quanto custa
Uma versão é reduzida ao que guarda, comprimida, criptografada com uma chave própria e guardada no armazenamento de objetos na UE, de onde todo servidor pode iniciar sandboxes. Só os bytes próprios dela contam, não a base por baixo. Templates não são cobrados: o seu plano limita o que as versões do espaço de trabalho ocupam juntas, 5 GiB no plano de US$ 20 e 30 GiB no plano de US$ 100 (Limits.template_gib; Workspace.template_bytes é o que elas ocupam agora). DeleteTemplate exclui todas as versões de um nome e libera o espaço na hora; os sandboxes feitos a partir dele continuam rodando, pausando e sendo retomados.
O nosso template: base
O base é Ubuntu 24.04 com ferramentas de build e git, Python 3, Node.js 22, Docker com Compose, Claude Code, Codex e OpenCode, e um desktop com Google Chrome. Nós o refazemos todo mês, e na hora em caso de correção de segurança do Chrome, do kernel ou de um pacote. Template.base nomeia a versão em que os sandboxes de um template iniciam, por um hash do que ela guarda: uma versão que você salva mantém a base em que o sandbox dela iniciou, então o seu template não muda sem você saber.
Não há build a partir de um Dockerfile: rode os passos do seu Dockerfile em um sandbox, ou docker build dentro dele, e salve esse sandbox.
Quando não funciona
RESOURCE_EXHAUSTEDcomLimitReached,template_gib: as versões do espaço de trabalho ocupam o espaço do plano, ou outra versão está sendo salva. Exclua um template antigo, ou espere o salvamento.LimitReached,template_versions: o nome tem 10 versões. Salve com um nome novo, ou exclua o template e salve de novo.- A versão está FAILED:
failure_messagediz por quê, como uma versão cujos bytes próprios passaram do espaço restante. Libere espaço, depois salve de novo. INVALID_ARGUMENTnomeando um tamanho: o tamanho é menor que omin_sizeda versão. Peça esse tamanho ou um maior.- O primeiro sandbox de uma versão nova é lento: o servidor buscou a versão, a cerca de 10 s por GiB. Os seguintes ali iniciam em cerca de 0,22 s.
Perguntas
Como faço um template de sandbox personalizado?
Configure um sandbox como quer os novos, depois chame CreateTemplate com um nome e o id dele. Inicie novos sandboxes com esse nome.
Um template guarda processos rodando?
Não: só arquivos e configurações. Para copiar um sandbox rodando com a memória e os processos, faça um fork dele.
Templates são cobrados?
Não. O seu plano limita quantos GiB os templates do espaço de trabalho ocupam no armazenamento de objetos.
Posso fazer um template a partir de um Dockerfile?
Não diretamente: rode os passos do Dockerfile, ou docker build, em um sandbox, depois salve o sandbox como template.
Imagens Docker sobrevivem em um template?
Sim. As imagens e os containers do Docker ficam no disco do sandbox, que o template guarda.
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.