---
title: "Templates: inicie sandboxes prontos para trabalhar | Pethost Agent Sandboxes"
description: "Salve o disco de um sandbox como template, com os seus pacotes e imagens Docker, e inicie novos sandboxes a partir dele em qualquer servidor em cerca de 0,2 s."
---

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

# Templates: inicie sandboxes prontos para trabalhar

Atualizado em 22 de novembro de 2026 · 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](https://pethost.dev/pt/docs/sandboxes/commands-and-files/)). 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](https://pethost.dev/pt/docs/sandboxes/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.

[AnteriorUso do computador: Chrome em um desktop dentro de um sandbox](https://pethost.dev/pt/docs/sandboxes/computer-use/) [PróximaSegredos e saída: chaves que um sandbox nunca guarda](https://pethost.dev/pt/docs/sandboxes/secrets-and-egress/)

## 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/)
