Docs do Agent Sandboxes · Começar
Como o Pethost Agent Sandboxes funciona
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.
- 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.
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.
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
urlda 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
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
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
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
| 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 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_PRECONDITIONcom o detalheStopped; - uma requisição a uma porta responde HTTP 503, “stopped: resume it”;
- só
ResumeSandboxo 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.
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.