---
title: "Como o Pethost Agent Sandboxes funciona | Pethost Agent Sandboxes"
description: "O que é um sandbox, seus três estados RUNNING, PAUSED e STOPPED, o que o acorda, as duas APIs e onde ficam a memória, os processos e os arquivos dele."
---

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

# Como o Pethost Agent Sandboxes funciona

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

Um sandbox é uma VM Linux que o seu código ou o seu agente inicia em cerca de 0,15 s, usa por uma API e deixa de lado. Quando nada acontece nele, ele pausa com a memória e os processos e, mais tarde, para com só o disco. A próxima chamada o acorda onde ele estava. Esta página é o modelo: o que é um sandbox, seus três estados, o que o leva de um ao outro e onde fica cada byte.

**Em resumo**

- **Uma microVM por sandbox:** Firecracker, kernel próprio, root lá dentro, Ubuntu com Python, Node.js, Docker, três agentes de código e Chrome.
- **Três estados:** RUNNING na memória do servidor, PAUSED no disco do servidor com memória e processos guardados, STOPPED no armazenamento de objetos com só o disco.
- **Acorda quando usado:** qualquer chamada a um sandbox pausado, um login SSH ou uma requisição a uma das portas dele o retoma em cerca de 0,1 s.
- **Duas APIs:** o painel guarda o registro de cada sandbox, e o servidor do próprio sandbox roda o que acontece dentro dele. Os SDKs e a CLI escondem a diferença.
- **Cobrado por segundo** em cada estado: [cobrança](https://pethost.dev/pt/docs/sandboxes/billing/).

## O que é um sandbox

Um sandbox é uma máquina virtual, feita a partir de um template. Dentro dele você é root, e os comandos rodam como o usuário `user`, que tem sudo sem senha, em `/home/user`. O hostname dele é o seu id: 16 caracteres, letras minúsculas e dígitos.

O nosso template, `base`, tem Ubuntu 24.04 com ferramentas de build e git, Python 3, Node.js 22, Docker, os agentes de código Claude Code, Codex e OpenCode, e um desktop com Google Chrome. Dois deles só iniciam no primeiro uso e não custam nada até lá: o desktop, na primeira captura de tela ou no primeiro link do desktop (alguns segundos), e o daemon do Docker, na primeira conexão a `/var/run/docker.sock`.

## Isolamento: uma microVM Firecracker para cada um

Cada sandbox é uma microVM Firecracker própria, com o próprio kernel Linux. O Firecracker roda cada VM dentro do jailer dele: chroot próprio, um usuário sem privilégios, um cgroup, um filtro seccomp e um namespace de rede próprio. O guest é seu, root e kernel incluídos; o host decide o que ele recebe.

- **O tamanho é imposto pelo host.** Uma VM recebe do servidor as vCPUs e a memória do seu tamanho, e nada que o guest diga muda isso.
- **Identidade própria.** Cada sandbox recebe aleatoriedade nova do kernel, hostname próprio e machine-id próprio, mesmo quando inicia do mesmo snapshot que outro.
- **Nenhum segredo lá dentro.** Os segredos do espaço de trabalho nunca entram em uma VM, e os tokens de API também não: um sandbox é acessado com um token só para ele, que expira.

## Tamanhos

Um sandbox tem um de quatro tamanhos, por toda a vida da sua VM:

| Tamanho | vCPUs | Memória | Disco |
| --- | --- | --- | --- |
| SMALL | 2 | 4 GiB | 10 GiB |
| DEFAULT | 4 | 8 GiB | 20 GiB |
| LARGE | 8 | 16 GiB | 40 GiB |
| XLARGE | 16 | 32 GiB | 80 GiB |

O disco é o que o sandbox pode gravar: os arquivos do próprio template não contam. Um novo tamanho (`UpdateSandbox`) reinicia um sandbox RUNNING em uma VM desse tamanho, com os arquivos guardados e os processos encerrados; um STOPPED assume o novo tamanho no próximo início, e um PAUSED precisa ser retomado ou parado antes. Um novo tamanho mantém o disco, a não ser que você defina `grow_disk`, que o aumenta até o do novo tamanho. Um disco nunca diminui.

## Templates

Um template é o conjunto de arquivos com que um sandbox inicia. O nosso é o `base`, refeito todo mês e na hora em caso de correção de segurança. O seu é o disco de um sandbox salvo com `CreateTemplate`: os arquivos, os pacotes que você instalou e as imagens Docker. Um template não guarda memória, processos nem conversas de agentes: um sandbox feito a partir dele inicia do zero.

Cada salvamento é uma nova versão, `name@1`, `name@2`, e um sandbox iniciado a partir de `name` pega a mais recente. Todo servidor inicia sandboxes de qualquer versão. O `min_size` de uma versão é o menor tamanho cujo disco comporta o que ela salvou. Um sandbox do seu próprio template inicia em cerca de 0,22 s quando o servidor já tem a versão; o primeiro em cada servidor a busca, a cerca de 10 s por GiB: [templates](https://pethost.dev/pt/docs/sandboxes/templates/).

## Duas APIs: o painel e o servidor do sandbox

Dois serviços respondem, conforme o que sabem:

- **SandboxService** é o painel, em `https://console.pethost.dev`, chamado com o seu token de API. Ele guarda o espaço de trabalho e cada sandbox como um registro: criação, configurações, pausa, retomada, fork, exclusão, templates, volumes, eventos e uso.
- **SandboxRuntimeService** é o servidor do próprio sandbox, na `url` da conexão dele, chamado com um token de conexão só para aquele sandbox. Ele roda o que acontece lá dentro: comandos, arquivos, o desktop, agentes de código e links.

Os SDKs e a CLI fazem a conexão para você: `run_command` é uma chamada, e o SDK encontra o servidor e mantém o token válido. As chamadas de runtime vão direto ao servidor, então o painel nunca fica no caminho do que roda dentro de um sandbox, e um servidor roda os seus sandboxes sem o painel.

## Os três estados

**RUNNING**

Na memória do servidor

Roda os seus processos e responde a toda chamada.

US$ 0,036 por hora, DEFAULT

Ocioso por 5min, ou PauseSandbox

Qualquer chamada, login SSH ou requisição a uma porta, em cerca de 0,1 s

**PAUSED**

No disco do servidor

Guarda memória, processos e disco, e o seu lugar no servidor.

US$ 0,0108 por hora, DEFAULT

Ocioso por 30min, ou StopSandbox

**STOPPED**

No armazenamento de objetos

Guarda o disco; os processos terminam.

US$ 0,03 por GiB ao mês dos próprios dados

ResumeSandbox o inicia de novo: cerca de 0,2 s com o disco no servidor, cerca de 10 s por GiB a partir do armazenamento de objetos

Os timers padrão, contados a partir da última coisa que aconteceu no sandbox. Um sandbox RUNNING também pode parar na hora, e qualquer sandbox pode ser excluído.

| Estado | Onde fica | O que guarda | Como acorda |
| --- | --- | --- | --- |
| RUNNING | Na memória do servidor | Tudo, rodando | Já está acordado |
| PAUSED | No disco do servidor | Memória, processos, disco | Na próxima chamada, login SSH ou requisição a uma porta, em cerca de 0,1 s; nunca recusado por falta de espaço |
| STOPPED | No armazenamento de objetos, e no disco do servidor enquanto houver espaço | O disco | Por `ResumeSandbox`, ou como um pausado com `wake_when_stopped` |
| DELETED | Em lugar nenhum | O registro por 30 dias, os eventos e as métricas por um dia | Nunca |

## Por que o PAUSED existe

A VM de um agente passa a maior parte do tempo esperando: o modelo pensar, uma pessoa ler a resposta, a próxima mensagem. Pará-la encerra os processos e, com eles, o servidor de desenvolvimento, o REPL, o estado do shell e o navegador aberto que o agente usava. Mantê-la RUNNING paga o preço cheio pela espera.

O PAUSED guarda tudo, memória e processos incluídos, por 30% do preço rodando, e o servidor guarda o lugar do sandbox, então uma retomada nunca é recusada por falta de espaço. O seu código não faz nada para acordá-lo: a próxima chamada ao sandbox o retoma antes, em cerca de 0,1 s, e a chamada então roda como se o sandbox nunca tivesse parado. Um sandbox pausado leva 41 ms no servidor para ser retomado, e um comando enviado a ele responde em cerca de 80 ms.

## O que muda o estado de um sandbox

| De | Para | O que o muda |
| --- | --- | --- |
| RUNNING | PAUSED | O timer de pausa; `PauseSandbox`; o servidor com pouca memória, depois de um minuto ocioso; a máquina do servidor reiniciando (MAINTENANCE, que não conta nada) |
| PAUSED | RUNNING | Qualquer chamada de runtime, um login SSH ou uma requisição a uma porta (WAKE); `ResumeSandbox` |
| RUNNING ou PAUSED | STOPPED | O timer de parada; `StopSandbox`; o servidor com pouco disco (um pausado); um espaço de trabalho sem como pagar (UNPAID); uma falha da VM ou do servidor (CRASH) |
| STOPPED | RUNNING | `ResumeSandbox`; uma chamada, um login SSH ou uma requisição a uma porta só com `wake_when_stopped`, e nunca depois de um CRASH |
| Qualquer | DELETED | `DeleteSandbox`; o timer de exclusão; a perda do servidor, para um sandbox sem cópia no armazenamento de objetos |

Cada mudança tem um motivo, `state_reason`, e palavras para pessoas, `state_message`. [Ciclo de vida e ociosidade](https://pethost.dev/pt/docs/sandboxes/lifecycle/) diz o que conta como atividade e como definir os timers.

## O que acorda um sandbox

Qualquer chamada do SandboxRuntimeService, um login SSH ou uma requisição a uma das portas dele primeiro retoma um sandbox PAUSED, no próprio servidor. Um sandbox STOPPED só acorda assim quando o ciclo de vida dele diz `wake_when_stopped`. Sem isso:

- uma chamada de runtime responde `FAILED_PRECONDITION` com o detalhe `Stopped`;
- uma requisição a uma porta responde HTTP 503, “stopped: resume it”;
- só `ResumeSandbox` o inicia.

Um sandbox parado por um CRASH só inicia de novo por `ResumeSandbox`. Enquanto o disco de um sandbox parado é buscado de volta do armazenamento de objetos, as chamadas a ele respondem `UNAVAILABLE` com `Restoring`, e `ResumeSandbox` espera até 45 s e depois diz em que ponto a busca está (`Sandbox.restore`).

## Onde ficam os seus dados

| O quê | Pausa | Parada | Fork | Template | Exclusão |
| --- | --- | --- | --- | --- | --- |
| Memória | Guardada | Perdida | Copiada | Não salva | Some |
| Processos rodando | Guardados | Encerrados | Copiados, rodando | Não salvos | Somem |
| Arquivos e imagens Docker | Guardados | Guardados | Copiados | Salvos | Somem |
| Conversas de agentes | Guardadas | Guardadas | Copiadas | Não salvas | Somem |

O disco de um sandbox parado é copiado para o armazenamento de objetos na UE um minuto depois que ele para, em blocos criptografados com uma chave só daquele sandbox; a memória nunca é copiada para lá. O servidor guarda a própria cópia enquanto tem espaço. Um volume é diferente: ele fica no disco de um servidor e não é copiado para lugar nenhum, então guarde também em outro lugar o que precisa sobreviver à perda de um servidor.

## Mudanças de servidor e servidores perdidos

Um sandbox STOPPED com uma cópia atual e sem volume inicia em outro servidor quando o seu não tem espaço para ele, e os endereços dele vão junto: a `url` da conexão, as URLs das portas e o `ssh_command`. Um sandbox PAUSED nunca muda de servidor: ele é retomado no servidor que guarda a memória dele.

Se um servidor é perdido, cada sandbox dele com cópia vira STOPPED a partir da última cópia e inicia em outro servidor no próximo `ResumeSandbox`. Um sandbox sem cópia é excluído, assim como os volumes daquele servidor.

## Perguntas

### Um sandbox é um container?

Não. Cada sandbox é uma microVM Firecracker com o próprio kernel Linux, e você é root dentro dela. Você pode rodar containers Docker dentro de um sandbox.

### O que acontece com os meus processos quando um sandbox pausa?

Eles param onde estão e guardam a memória, os arquivos abertos e o estado. A próxima chamada, login SSH ou requisição a uma porta os retoma em cerca de 0,1 s, como se nada tivesse acontecido.

### Um sandbox pausado pode deixar de acordar por falta de espaço?

Não. O servidor guarda o lugar dele enquanto está pausado, então uma retomada nunca é recusada por falta de espaço. Um sandbox parado pode: aí `ResumeSandbox` pode iniciá-lo em outro servidor.

### Onde ficam os meus arquivos quando um sandbox está parado?

No disco dele, copiado para o armazenamento de objetos na UE, criptografado com uma chave daquele sandbox, e no servidor enquanto houver espaço. Eles voltam como estavam quando o sandbox é retomado.

### Um template guarda processos rodando?

Não. Um template salva só o disco: arquivos, pacotes e imagens Docker. Um sandbox feito a partir dele inicia do zero, sem nenhum processo nem conversa de agente do sandbox de onde foi salvo. Para copiar um sandbox rodando, faça um fork dele.

[AnteriorDocs do Pethost Agent Sandboxes](https://pethost.dev/pt/docs/sandboxes/) [PróximaInício rápido: o seu primeiro sandbox](https://pethost.dev/pt/docs/sandboxes/quickstart/)

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