---
title: "Boas práticas do Pethost Agent Sandboxes | Pethost Agent Sandboxes"
description: "As escolhas que fazem sandboxes iniciarem rápido, custarem menos e ficarem seguros: templates, pausa, jobs em lote, keep_awake, request_id, segredos, saída."
---

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

# Boas práticas do Pethost Agent Sandboxes

Atualizado em 22 de novembro de 2026 · 9 min de leitura

Algumas escolhas decidem a rapidez com que os seus sandboxes iniciam, quanto custam enquanto esperam e o que um agente dentro deles consegue alcançar. Cada prática abaixo é uma regra, o número por trás dela e os campos que a aplicam. A maioria é uma configuração que você faz uma vez.

**Em resumo**

- **Velocidade:** salve a sua preparação como um template, inicie servidores com `wait_for_port` e faça fork para tentativas em paralelo.
- **Custo:** deixe o sandbox de um agente pausar em vez de parar, exclua sandboxes de lote quando terminarem e comece pequeno.
- **Confiabilidade:** marque comandos longos com `keep_awake`, repita com `request_id`, use streams em vez de consultas repetidas e guarde em volumes o que precisa sobreviver a um sandbox.
- **Segurança:** ligue chaves de API como segredos, restrinja a saída para código que você não escreveu e trate tudo o que um sandbox devolve como dados.
- **Organização:** dê rótulos a todo sandbox e liste-os por rótulo.

Velocidade

## Salve a sua preparação como um template

Instalar as dependências a cada início custa os mesmos minutos toda vez. Instale-as uma vez em um sandbox e salve o disco dele com `CreateTemplate`: pacotes, caches de build e imagens Docker incluídos. Um sandbox do seu template inicia em cerca de 0,22 s com tudo no lugar, em qualquer servidor: o primeiro em cada servidor busca a versão, a cerca de 10 s por GiB, e os seguintes iniciam da cópia dele. Deixe segredos fora dos arquivos que você salva, já que todo sandbox feito a partir do template os recebe, e crie uma nova versão quando as dependências mudarem: `my-app` inicia da mais recente, `my-app@3` daquela.

## Inicie servidores com wait_for_port

Um servidor de desenvolvimento leva um instante para escutar, e consultá-lo de fora desperdiça chamadas. Rode-o com `wait_for_port`: `RunCommand` responde assim que algo escuta naquela porta, enquanto o comando continua rodando, então uma chamada inicia o servidor e diz que ele está no ar. Depois abra a porta publicamente, ou dê à sua página um token para ela: [portas e previews](https://pethost.dev/pt/docs/sandboxes/ports-and-previews/).

## Faça fork para tentativas em paralelo

Quando um agente deve tentar várias correções, ou um eval deve iniciar muitas execuções a partir de um estado preparado, faça fork do sandbox em vez de reconstruir esse estado. `ForkSandbox` copia memória, processos e disco para até 100 novos sandboxes em uma chamada: uma cópia levou cerca de 0,25 s. Cada cópia é um início, e todas são criadas ou nenhuma. Duas coisas a saber:

- **Gere novas sementes para os geradores aleatórios** nas cópias. Cada cópia tem aleatoriedade própria do kernel, mas os geradores aleatórios que já rodam nos processos dela (o do OpenSSL, o do Python, o do Node, o do Go) dão os mesmos números em todas as cópias até receberem uma nova semente.
- **Um volume de leitura e escrita recusa um fork**, já que só um sandbox pode gravar nele. Um volume só é montado na criação, então monte-o com `read_only` em um sandbox de que você pretende fazer fork.

Custo

## Deixe o sandbox de um agente pausar, não parar

O sandbox de um agente passa a maior parte do tempo esperando, e pará-lo encerra os processos: o servidor de desenvolvimento, o REPL, o navegador que ele tinha aberto. Mantenha o timer de pausa e aumente o timer de parada ou desative-o (`stop_after_idle_seconds` 0). Pausado, o sandbox custa 30% do preço rodando e acorda na próxima chamada em cerca de 0,1 s, com tudo onde estava. Um sandbox DEFAULT que trabalha 2 horas por dia e fica pausado no resto custa cerca de US$ 9,42 por mês, contra US$ 26,28 sempre rodando.

**A sessão de um agente**Pausa entre turnos, nunca para

1. rodando
2. pausado
3. rodando
4. pausado

**O sandbox de um usuário no seu app**Pausa, depois para após meia hora

1. rodando
2. pausado
3. parado

**Um preview que dorme**Acorda a cada visita

1. pausado
2. rodando
3. pausado
4. rodando
5. pausado

**Um job em lote**Roda, depois é excluído

1. rodando
2. parado
3. excluído

- RUNNING
- PAUSED
- STOPPED
- DELETED

Quatro jobs ao longo de um dia, cada um com o próprio ciclo de vida. Os valores estão em [ciclo de vida e ociosidade](https://pethost.dev/pt/docs/sandboxes/lifecycle/#presets).

## Exclua sandboxes de lote quando terminarem

Um sandbox para um só job, uma execução de testes ou um caso de eval, não deve custar nada depois que o job termina. Chame `DeleteSandbox` no fim e defina `delete_after_idle_seconds` como rede de segurança para um job que morre antes de chegar lá. Desative o timer de pausa e dê um timer de parada curto, para que o sandbox de um job ocioso vá embora rápido. Um sandbox parado que você esquece custa US$ 0,03 por GiB ao mês, todo mês. Inícios são grátis, então um sandbox novo por job custa só os segundos dele: 1.000 execuções de 40 s em SMALL custam US$ 0,20.

## Comece pequeno e mude de tamanho quando precisar

Um tamanho é o conjunto de vCPUs, memória e disco, e o preço dobra a cada tamanho acima. Comece com SMALL, US$ 0,018 por hora, e acompanhe `GetSandboxMetrics`. Quando um job precisa de mais, `UpdateSandbox` com um novo tamanho reinicia um sandbox RUNNING em uma VM desse tamanho, com os arquivos guardados, em cerca de 283 ms: os processos terminam, então mude de tamanho entre jobs. Adicione `grow_disk` para aumentar o disco até o do novo tamanho; um disco nunca diminui, então um sandbox que cresceu não pode voltar a um tamanho menor.

Confiabilidade

## Marque comandos longos com keep_awake

Um build ou uma suíte de testes pode rodar por minutos sem nenhuma chamada ao sandbox, e o timer de pausa o pausaria no meio do trabalho. Inicie-o com `keep_awake` e com `timeout_seconds`, para que um comando travado não mantenha o sandbox rodando para sempre. Um servidor não precisa de nenhum dos dois: uma requisição à porta dele acorda o sandbox. [Ciclo de vida e ociosidade](https://pethost.dev/pt/docs/sandboxes/lifecycle/#keep-awake) tem os detalhes.

## Repita com request_id

A rede pode perder a resposta de uma chamada que já fez o trabalho. Uma chamada que cria algo recebe um `request_id`: uma nova tentativa com o mesmo id em até 24 horas responde o que a primeira chamada fez e não faz nada de novo. `CreateSandbox`, `ForkSandbox`, `CreateTemplate`, `CreateVolume`, `RunCommand` e `PromptAgent` recebem um. Gere-o uma vez para cada coisa que você pretende fazer, guarde-o e envie-o de novo a cada nova tentativa. Uma ressalva: um sandbox guarda no disco os ids do que roda nele, então um que parou pode ter perdido os dos últimos segundos, e uma nova tentativa de um comando desses o roda de novo.

Python

```
import uuid

from pethost.sandboxes import Label, Sandboxes

sandboxes = Sandboxes()  # The token: PETHOST_TOKEN.
request_id = str(uuid.uuid4())  # Keep it: a retry sends the same one.

sandbox = sandboxes.create_sandbox(
    template="my-app",
    labels=[Label(key="user", value="42"), Label(key="job", value="nightly-evals")],
    request_id=request_id,
)
```

TypeScript

```
import { Sandboxes } from "pethost/sandboxes";

const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const requestId = crypto.randomUUID(); // Keep it: a retry sends the same one.

const sandbox = await sandboxes.createSandbox({
  template: "my-app",
  labels: [{ key: "user", value: "42" }, { key: "job", value: "nightly-evals" }],
  requestId,
});
```

Go

```
requestID := rand.Text() // crypto/rand. Keep it: a retry sends the same one.

sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template:  "my-app",
	Labels:    []sandboxes.Label{{Key: "user", Value: "42"}, {Key: "job", Value: "nightly-evals"}},
	RequestID: requestID,
})
```

Rust

```
let request_id = uuid::Uuid::new_v4().to_string(); // Keep it: a retry sends the same one.

let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "my-app".into(),
        labels: vec![
            Label { key: "user".into(), value: "42".into() },
            Label { key: "job".into(), value: "nightly-evals".into() },
        ],
        request_id: request_id.clone(),
        ..Default::default()
    })
    .await?;
```

MCP

```
CreateSandbox {"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}
```

HTTP

```
curl https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
  -H "Authorization: Bearer $PETHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "my-app", "labels": [{"key": "user", "value": "42"}], "request_id": "b7e1c2d4-0f3a-4c55-9a7e-2d1f6c8e9a10"}'
```

## Use streams em vez de consultas repetidas

Consultar um comando ou um sandbox repetidamente custa uma chamada a cada vez e ainda descobre tarde. Uma chamada que espera faz a espera por você: `RunCommand`, `GetCommand`, `PromptAgent` e `GetAgentTurn` esperam até 45 s (`wait_seconds`) e respondem assim que o trabalho termina. Para acompanhar o trabalho enquanto acontece, use um stream: `WatchCommand` para a saída de um comando, `WatchConversation` para as mensagens e chamadas de ferramenta de um agente, `WatchSandboxEvents` para o ciclo de vida, os comandos e as conexões de um sandbox.

## Use volumes só para o que precisa sobreviver a um sandbox

Um volume é um disco fora de todo sandbox, montado em um caminho: datasets, caches compartilhados por muitos sandboxes, os arquivos de um banco de dados. Ele fica no disco de um servidor e não é copiado para lugar nenhum, então, se esse servidor for perdido, o volume também será. Um sandbox que monta um volume não pode mudar de servidor, e uma montagem de leitura e escrita recusa forks. A maior parte do trabalho não precisa de volume: o disco do próprio sandbox sobrevive a pausas e paradas, e um template leva arquivos para novos sandboxes. O que não pode se perder, envie também para um armazenamento seu.

Segurança

## Ligue chaves de API como segredos

Uma chave em uma variável de ambiente comum pode ser lida por todo processo no sandbox, e por um agente que imprime o próprio ambiente. Em vez disso, salve-a como um segredo do espaço de trabalho, com os hosts a que ela se destina (`SetSecret`: `anthropic`, `api.anthropic.com`), e ligue uma variável a ele (`ANTHROPIC_API_KEY`, segredo `anthropic`). A variável passa a guardar um marcador, `phs_…`, e o proxy de saída coloca a chave real nos cabeçalhos das requisições HTTPS só para esses hosts. Um novo valor funciona na hora em todo sandbox que o liga: [segredos e saída](https://pethost.dev/pt/docs/sandboxes/secrets-and-egress/#secrets).

## Restrinja a saída para código que você não escreveu

Por padrão, um sandbox pode se conectar a qualquer lugar. Para código não confiável, liste aonde ele pode ir (`egress.allow`): um domínio como `pypi.org`, os subdomínios dele com `*.github.com` (que deixa de fora o próprio `github.com`), um IP ou um CIDR, cada um com uma porta quando não for 80 e 443, como `github.com:22` para git por SSH. `deny` vence `allow`. O DNS do sandbox só responde nomes que a lista permite, e só TCP e DNS saem de um sandbox: nada de UDP, nada de ping. Uma mudança vale na hora e fecha as conexões que ela não permite mais.

## Trate o que um sandbox devolve como dados

A saída de comandos, o conteúdo de arquivos, as mensagens de um agente, as capturas de tela e as páginas que um navegador carrega vêm de programas e da internet. Quando um modelo os lê, eles são dados, nunca instruções: um README ou uma página web pode ter texto escrito para conduzir um agente. Mantenha essa linha nos seus prompts e não dê a um sandbox que roda trabalho não confiável mais segredos nem uma saída mais ampla do que o trabalho precisa.

Organização

## Dê rótulos a todo sandbox

Um rótulo é uma chave e um valor seus: `user=42`, `job=nightly-evals`, `run=7f3a`. Um sandbox aceita até 32, e `ListSandboxes` lista os sandboxes que têm todos os rótulos que você indicar. Assim o seu app encontra os sandboxes de um usuário sem uma tabela própria, um job de limpeza encontra as sobras de uma execução e o painel mostra de quem é cada sandbox. Um rótulo serve para encontrar muitos; um `name` serve para chamar um: único no espaço de trabalho, até 63 caracteres de a-z, 0-9 e “-”, e `ListSandboxes` com `name` encontra o id dele.

## Perguntas

### Devo parar ou pausar um sandbox ocioso?

Pause quando os processos importam ou quando ele vai ser usado de novo em breve: ele acorda em cerca de 0,1 s onde estava, por 30% do preço rodando. Pare para um sono longo: aí ele custa só os dados guardados.

### Como faço os sandboxes iniciarem mais rápido?

Salve a sua preparação como um template, para que nada seja instalado no início: um sandbox feito a partir dele inicia em cerca de 0,22 s com os seus pacotes e imagens Docker.

### Como mantenho chaves de API fora de um sandbox?

Salve cada chave como um segredo do espaço de trabalho com os hosts dela e ligue uma variável de ambiente a ela. O sandbox vê um marcador, e o proxy de saída adiciona a chave real às requisições para esses hosts.

### Quantos sandboxes posso rodar ao mesmo tempo?

Quantos as vCPUs do seu plano comportarem, rodando ou pausados: 10 SMALL no plano de US$ 20, 64 no plano de US$ 100. Sandboxes parados não contam.

[AnteriorPreços e cobrança de sandboxes: por segundo, por estado](https://pethost.dev/pt/docs/sandboxes/billing/) [PróximaRode comandos e edite arquivos em um sandbox](https://pethost.dev/pt/docs/sandboxes/commands-and-files/)

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