Português
Começar

Agent Sandboxes Uma URL para cada porta

Um endereço HTTPS para cada porta

Um dev server em um sandbox é uma URL de preview que você pode mandar para alguém. Não há nada para registrar nem para esperar, e um preview que ninguém está vendo pausa por 30% do preço até a próxima visita acordá-lo.

O endereço

Toda porta de um sandbox tem um endereço HTTPS próprio, https://<port>-<sandbox id>.<server>: por exemplo, https://3000-k3x9q2m7v1c8p4ra.sbx1.sandboxes.pethost.network. Cada servidor tem um registro DNS wildcard e um certificado para todo nome abaixo dele, então um sandbox novo não precisa de registro próprio, e os endereços dele funcionam assim que ele inicia.

O servidor passa cada requisição ao que escuta nessa porta dentro do sandbox, inclusive em localhost, então um dev server não precisa de --host 0.0.0.0. HTTP/1.1 e HTTP/2 funcionam, WebSockets incluídos, e as portas de um sandbox atendem até 896 requisições ao mesmo tempo. Um dev server que confere o cabeçalho Host, como o do Vite, precisa do host do preview nos hosts permitidos.

from pethost.sandboxes import Ingress, PublicPort, Sandboxes, SandboxSettings

sandboxes = Sandboxes()  # lê o PETHOST_TOKEN
box = sandboxes.create_sandbox(settings=SandboxSettings(
    ingress=Ingress(public_ports=[PublicPort(port=3000)])))
sandboxes.run_command(box.sandbox_id, command="python3 -m http.server 3000",
                      wait_for_port=3000)
print(sandboxes.get_sandbox(box.sandbox_id).settings.ingress.public_ports[0].url)
# https://3000-k3x9q2m7v1c8p4ra.sbx1.sandboxes.pethost.network

private = sandboxes.create_link(box.sandbox_id, port=8080)  # uma porta privada
print(private.url, private.token)  # uma requisição envia Pethost-Token: <token>
pethost sandbox new --name web --public-port 3000
pethost sandbox run web --wait-for-port 3000 -d -- python3 -m http.server 3000
pethost sandbox url web 3000
pethost sandbox url web 8080 --token   # uma porta privada, e o token dela

Público ou privado

Uma porta listada nas configurações de ingress do sandbox é pública: qualquer pessoa com o endereço a abre. Um sandbox lista até 20, na criação ou depois, e nenhuma por padrão.

Todas as outras portas são privadas. Uma porta privada só responde a uma requisição que leva Pethost-Token: <token>, com um token que create_link cria só para aquela porta, válido por uma hora por padrão e um dia no máximo. O servidor o confere antes de qualquer coisa acordar e tira o cabeçalho, então o seu programa nunca o vê; uma requisição sem ele recebe 401. Uma página de qualquer origem pode chamar a porta com o token, já que o servidor responde ao CORS por ela, então o frontend do seu produto pode falar com o sandbox de um usuário sem tornar uma porta pública.

Uma aba do navegador, um WebSocket ou uma imagem não enviam esse cabeçalho. O que uma pessoa abre no navegador é uma porta pública, ou uma privada encaminhada para o computador dela com ssh -L.

URLs de preview que dormem

Um preview para cada um dos seus usuários são poucas chamadas: um template com o projeto e as dependências instaladas, um sandbox a partir dele, o dev server iniciado por run_command com wait_for_port, a porta pública e um timer de pausa curto. Quando ninguém olha, o sandbox pausa com a memória, e com ela o dev server, a US$ 0,0054 por hora para SMALL em vez de US$ 0,018. A próxima visita o acorda em cerca de 0,2 s, e o servidor responde de onde parou. Um sandbox pausado mantém o lugar no servidor, então acordar nunca é recusado por falta de espaço.

Um sandbox STOPPED responde às portas com 503, “stopped: resume it”, a não ser que o ciclo de vida dele diga wake_when_stopped. Aí uma visita o inicia, e as vCPUs dele contam no seu plano enquanto está parado. Quando um sandbox pausa e para.

Limites e preços

Sem domínio próprio: os endereços ficam sob o servidor do sandbox. Até 20 portas públicas. As portas levam HTTP e WebSockets; uma porta TCP pura, como a de um banco de dados, é alcançada com ssh -L. O endereço de todo sandbox fica sob um mesmo domínio, então o servidor tira o Domain de qualquer cookie que uma resposta define: dê aos cookies do seu app o prefixo __Host-. As requisições a cada porta aparecem nos eventos do sandbox, uma linha por minuto com as requisições, as respostas 5xx e os bytes. Uma porta não tem preço próprio: as requisições mantêm o sandbox acordado, cobrado por segundo pelo preço do tamanho, e ocioso ele pausa.

Como se compara

Em 21 de novembro de 2026, o boat.dev dava a uma porta uma URL com um token por padrão, até 50 portas, e o Vercel Sandbox abria até 15 portas. Nenhum dos dois pausava um preview com a memória: o boat.dev não tem pausa, e um sandbox parado do Vercel guardava só o sistema de arquivos. Um preview pausado do Pethost responde ao próximo visitante com o dev server como estava.

Ler a documentação

Perguntas

Posso usar o meu próprio domínio nas URLs de preview?

Não: todo endereço fica sob o nome do servidor do sandbox.

WebSockets funcionam?

Sim, em portas públicas a partir de um navegador, e em privadas a partir de um programa que envia o token.

Uma visita acorda um sandbox pausado?

Sim, em cerca de 0,2 s. Um parado responde 503, a não ser que o ciclo de vida dele o acorde quando parado.

Como mantenho uma porta privada?

Deixe-a fora das portas públicas: toda porta é privada a não ser que esteja listada, e um token de create_link a abre para um programa.

Relacionados

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

Começar o teste grátis