Português
Menu da documentação

Docs do Agent Sandboxes · Começar

Como o Pethost Agent Sandboxes funciona

Atualizado em · 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.

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:

TamanhovCPUsMemóriaDisco
SMALL24 GiB10 GiB
DEFAULT48 GiB20 GiB
LARGE816 GiB40 GiB
XLARGE1632 GiB80 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 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.
EstadoOnde ficaO que guardaComo acorda
RUNNINGNa memória do servidorTudo, rodandoJá está acordado
PAUSEDNo disco do servidorMemória, processos, discoNa próxima chamada, login SSH ou requisição a uma porta, em cerca de 0,1 s; nunca recusado por falta de espaço
STOPPEDNo armazenamento de objetos, e no disco do servidor enquanto houver espaçoO discoPor ResumeSandbox, ou como um pausado com wake_when_stopped
DELETEDEm lugar nenhumO registro por 30 dias, os eventos e as métricas por um diaNunca

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

DeParaO que o muda
RUNNINGPAUSEDO 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)
PAUSEDRUNNINGQualquer chamada de runtime, um login SSH ou uma requisição a uma porta (WAKE); ResumeSandbox
RUNNING ou PAUSEDSTOPPEDO 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)
STOPPEDRUNNINGResumeSandbox; uma chamada, um login SSH ou uma requisição a uma porta só com wake_when_stopped, e nunca depois de um CRASH
QualquerDELETEDDeleteSandbox; 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_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êPausaParadaForkTemplateExclusão
MemóriaGuardadaPerdidaCopiadaNão salvaSome
Processos rodandoGuardadosEncerradosCopiados, rodandoNão salvosSomem
Arquivos e imagens DockerGuardadosGuardadosCopiadosSalvosSomem
Conversas de agentesGuardadasGuardadasCopiadasNão salvasSomem

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.

Começar o teste grátis