Português
Menu da documentação

Docs do Agent Sandboxes · Tarefas

Templates: inicie sandboxes prontos para trabalhar

Atualizado em · 6 min de leitura

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.

Em resumo
  • CreateTemplate salva 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.
  • CreateSandbox com "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.

Python
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
TypeScript
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);
Go
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)
Rust
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);
CLI
$ 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
MCP
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.

Python
preview = sandboxes.create_sandbox("my-app")
print(preview.sandbox_id, preview.template)  # 8j37xshusqwdz8cs my-app@1
TypeScript
const preview = await sandboxes.createSandbox({ template: "my-app" });
console.log(preview.sandboxId, preview.template);
Go
preview, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "my-app"})
if err != nil {
	log.Fatal(err)
}
fmt.Println(preview.SandboxID, preview.Template)
Rust
let preview = sandboxes
    .create_sandbox(CreateSandboxRequest { template: "my-app".into(), ..Default::default() })
    .await?;
println!("{} {}", preview.sandbox_id, preview.template);
CLI
$ 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
MCP
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_EXHAUSTED com LimitReached, 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_message diz por quê, como uma versão cujos bytes próprios passaram do espaço restante. Libere espaço, depois salve de novo.
  • INVALID_ARGUMENT nomeando um tamanho: o tamanho é menor que o min_size da 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.

Começar o teste grátis