Português
Começar

Agent Sandboxes Comandos, arquivos e um terminal

Um sandbox de execução de código para agentes de IA

Seu modelo escreve código, um sandbox o roda, e a saída volta na mesma chamada. Comandos, arquivos e terminais são uma API só, respondida pelo servidor em que o sandbox roda, não pelo painel.

Execução de código em uma chamada

Cada sandbox é uma microVM Firecracker com o próprio kernel Linux e root lá dentro, iniciada a partir do nosso template base em cerca de 0,15 s: Ubuntu 24.04 com ferramentas de build, Python 3, Node.js 22 e Docker. run_command roda um comando via bash -lc como user, que tem sudo, ou como root, em qualquer diretório que você indicar. A chamada espera até 45 segundos o comando terminar e responde o código de saída e os últimos 32 KiB do stdout e do stderr.

Três campos mudam o que a chamada espera:

  • wait_for_port responde assim que algo escuta em uma porta, enquanto o comando continua rodando: npm run dev e 5173.
  • wait_seconds=0 responde assim que o comando inicia. get_command espera por ele de novo, e watch_command transmite a saída, primeiro os últimos 64 KiB, depois ao vivo.
  • timeout_seconds encerra um comando que roda demais. Sem ele, só stop_command encerra um: SIGTERM, depois SIGKILL 10 s mais tarde.

Cada resposta diz quantos bytes o comando escreveu; devolva esse número e a próxima resposta traz só o que é novo. Com um request_id, uma nova tentativa em até 24 horas não roda nada de novo e responde o que a primeira chamada fez. list_commands mostra o que roda agora, inclusive comandos digitados por SSH, e os últimos 100 que terminaram ficam guardados.

from pethost.sandboxes import FileChange, Sandboxes, TextEdit

sandboxes = Sandboxes()  # lê o PETHOST_TOKEN
box = sandboxes.create_sandbox()
code = "x = 1\nprint(x * 42)\n"
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", text=code)])
out = sandboxes.run_command(box.sandbox_id, command="python3 app.py", timeout_seconds=30)
print(out.exit_code, out.stdout)  # 0 42

edit = TextEdit(old_text="x = 1", new_text="x = 2")
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", edit=edit)])
server = sandboxes.run_command(box.sandbox_id, command="python3 -m http.server 8000",
                               wait_for_port=8000)
print(server.state.name)  # RUNNING: respondeu quando a porta 8000 passou a escutar
pethost sandbox new --name tests --size small
pethost sandbox cp ./app tests:/home/user/app
pethost sandbox run tests --cwd /home/user/app -- python3 -m unittest
pethost sandbox open tests --terminal

Arquivos: lotes e edições exatas

write_files recebe uma lista de alterações e as faz em ordem: escrever o texto ou os bytes de um arquivo, substituir um texto que aparece exatamente uma vez nele, mover, excluir, criar um diretório, definir um modo. Diretórios pais que faltam são criados. Ele para na primeira alteração que falha e diz qual, com um motivo que o seu código pode tratar, como o texto a substituir não estar lá. Assim, uma edição só acontece onde o texto dela está. Uma requisição leva até 17 MiB.

read_file lê até 1 MiB a partir de qualquer posição, list_files lista um diretório até a profundidade que você pedir, e watch_files transmite cada alteração dentro dele. Um arquivo de qualquer tamanho passa por um link de create_link: uma URL de download envia o arquivo, ou um diretório como .tar; uma URL de upload recebe um PUT. Cada uma funciona uma vez.

Um terminal no navegador

create_link com um terminal dá uma página que roda bash, ou um comando como claude, e um WebSocket na mesma URL que leva os bytes dele, para um terminal dentro do seu próprio produto. Um link dura uma hora por padrão e um dia no máximo.

O que roda lá dentro

O Docker roda em todo sandbox: o dockerd inicia na primeira conexão ao socket dele e guarda as imagens no disco do sandbox, então elas sobrevivem a uma parada e um template as leva junto. O resto vem do apt, com sudo.

As chamadas vão direto para o servidor do sandbox, que o SDK encontra para você. O primeiro comando depois de uma criação responde em 29 a 48 ms. Em um servidor rodando 74 sandboxes, cada um fazendo build de um projeto JavaScript e esperando entre builds como um agente faz, um comando trivial levou 6 ms (28 ms no percentil 95).

Limites e preços

O quêLimite
Chamadas simultâneas, por sandbox64; um write_files conta como 16
Uma requisição1 MiB; write_files 17 MiB
Uma respostacerca de 64 KiB; read_file 1 MiB; qualquer tamanho por um link
Saída em uma respostaos últimos 32 KiB do stdout e do stderr

Comandos, arquivos e links não têm preço próprio: você paga pelos segundos rodando do sandbox, de US$ 0,018 por hora para SMALL (2 vCPU, 4 GiB) a US$ 0,144 para XLARGE (16 vCPU, 32 GiB), cada execução arredondada para cima ao segundo e no mínimo 10 s. Ocioso por 5 minutos, ele pausa por 30% disso. Como funciona a cobrança por segundo.

Como se compara

Em 21 de novembro de 2026, o E2B cobrava US$ 0,1656 por hora por um sandbox de 2 vCPU e 4 GiB, e o Daytona também; o SMALL do Pethost, do mesmo tamanho, custa US$ 0,018. As sessões do E2B duravam até 1 hora no plano Hobby e 24 horas no Pro, as do Vercel Sandbox 45 minutos no Hobby e 24 horas no Pro. Um sandbox do Pethost não tem limite de tempo de vida.

Ler a documentação

Perguntas

Que linguagens um sandbox de execução de código roda?

Qualquer coisa que rode no Linux. Python 3 e Node.js 22 vêm instalados, o Docker roda, e o apt instala o resto. Salve um sandbox com as suas ferramentas como template, e os novos sandboxes já iniciam com elas.

Por quanto tempo um comando pode rodar?

O quanto precisar: uma chamada espera até 45 segundos, depois você lê ou acompanha a saída. Ocioso por 5 minutos, um sandbox pausa com o comando na memória, que continua na próxima chamada. Um comando iniciado com keep_awake roda direto até o fim, e um que você acompanha com watch_command também.

O código pode acessar a internet?

Sim, por TCP: por padrão, um sandbox pode se conectar a qualquer lugar. Uma lista de permissões de saída restringe isso aos domínios, IPs e portas que você indicar. Nenhum UDP sai de um sandbox.

Como movo arquivos grandes?

Por um link de download ou de upload, de qualquer tamanho, ou com scp por SSH.

Relacionados

Dê um computador ao seu agente em 0,15 s

Começar o teste grátis