---
title: "Portas e previews: as URLs de um sandbox | Pethost Agent Sandboxes"
description: "Dê a qualquer porta de um sandbox um endereço HTTPS, público ou atrás de um token, espere um servidor de desenvolvimento escutar e rode previews que dormem."
---

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

# Portas e previews: as URLs de um sandbox

Atualizado em 22 de novembro de 2026 · 7 min de leitura

Cada porta de um sandbox tem um endereço HTTPS próprio, `https://<port>-<sandbox id>.<server>`. Torne uma porta pública e qualquer pessoa pode abri-la; deixe-a privada e ela só responde a requisições que levam o token dela. Uma requisição à porta de um sandbox pausado o acorda, então um preview pode dormir entre visitas.

**Em resumo**

- **`wait_for_port`** em `RunCommand`: a chamada responde assim que o seu servidor escuta, enquanto ele continua rodando.
- **Portas públicas** (`settings.ingress.public_ports`, até 20) respondem a qualquer um, inclusive a um navegador.
- **Portas privadas** respondem a requisições com `Pethost-Token: <token>`, de `CreateLink` com `port`: para programas, curl e o `fetch` de uma página.
- **Uma visita acorda um sandbox pausado** em cerca de 0,2 s, com o servidor onde estava.

### Step 1: Inicie um servidor e espere pela porta dele

Inicie o servidor com `wait_for_port`. A chamada responde assim que algo escuta naquela porta, dentro de `wait_seconds`, e o servidor continua rodando. Um servidor que escuta em `localhost` também é alcançado.

Python

```
server = sandboxes.run_command(
    sandbox_id,
    command="python3 -m http.server 5173",
    wait_for_port=5173,
)
print(server.state.name, server.command_id)  # RUNNING zldikyia4nbt
```

TypeScript

```
const server = await sandboxes.runCommand({
  sandboxId,
  command: "python3 -m http.server 5173",
  waitForPort: 5173,
});
console.log(server.state, server.commandId); // RUNNING
```

Go

```
server, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
	SandboxID:   id,
	Command:     "python3 -m http.server 5173",
	WaitForPort: 5173,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(server.State, server.CommandID) // RUNNING
```

Rust

```
let server = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: id.clone(),
        command: "python3 -m http.server 5173".into(),
        wait_for_port: 5173,
        ..Default::default()
    })
    .await?;
println!("{:?} {}", server.state, server.command_id); // Running
```

CLI

```
$ pethost sandbox run api-dev -d --wait-for-port 5173 -- python3 -m http.server 5173
It runs on in the sandbox. Its output so far:  pethost api GetCommand '{"sandbox_id": "e9bprbw1hovj6sw5", "command_id": "gqiwdee8y868"}'
gqiwdee8y868
```

### Step 2: Torne a porta pública

Uma porta pública fica nas configurações de `ingress` do sandbox. `UpdateSandbox` substitui o grupo inteiro, então envie todas as portas que devem continuar públicas; a resposta traz a `url` de cada uma.

Python

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

sandbox = sandboxes.update_sandbox(
    sandbox_id,
    settings=SandboxSettings(ingress=Ingress(public_ports=[PublicPort(port=5173)])),
)
for port in sandbox.settings.ingress.public_ports:
    print(port.port, port.url)
# 5173 https://5173-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network
```

TypeScript

```
const updated = await sandboxes.updateSandbox({
  sandboxId,
  settings: { ingress: { publicPorts: [{ port: 5173 }] } },
});
for (const port of updated.settings?.ingress?.publicPorts ?? []) console.log(port.port, port.url);
```

Go

```
updated, err := client.UpdateSandbox(ctx, &sandboxes.UpdateSandboxRequest{SandboxID: id, Settings: &sandboxes.SandboxSettings{
	Ingress: &sandboxes.Ingress{PublicPorts: []sandboxes.PublicPort{{Port: 5173}}},
}})
if err != nil {
	log.Fatal(err)
}
for _, port := range updated.Settings.Ingress.PublicPorts {
	fmt.Println(port.Port, port.URL)
}
```

Rust

```
let ingress = Ingress { public_ports: vec![PublicPort { port: 5173, ..Default::default() }] };
let updated = sandboxes
    .update_sandbox(UpdateSandboxRequest {
        sandbox_id: id.clone(),
        settings: Some(SandboxSettings { ingress: Some(ingress), ..Default::default() }),
        ..Default::default()
    })
    .await?;
for port in updated.settings.and_then(|settings| settings.ingress).map(|ingress| ingress.public_ports).unwrap_or_default() {
    println!("{} {}", port.port, port.url);
}
```

CLI

```
$ pethost sandbox ports api-dev --open 5173
5173   https://5173-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network
```

MCP

```
UpdateSandbox {"sandbox_id": "…", "settings": {"ingress": {"public_ports": [{"port": 5173}]}}}
```

Uma porta pode ser pública desde o início: passe o mesmo `ingress` para `CreateSandbox`, ou `--public-port 5173` para `pethost sandbox new`.

### Step 3: Ou mantenha-a privada, atrás de um token

Qualquer porta que não é pública só responde a uma requisição com o cabeçalho `Pethost-Token`. `CreateLink` com `port` responde com o endereço da porta e um token só para ela, que expira depois de uma hora, a não ser que `ttl_seconds` diga outra coisa. Aqui, um segundo servidor, iniciado como no primeiro passo, escuta na 8080.

Python

```
link = sandboxes.create_link(sandbox_id, port=8080, ttl_seconds=3600)
print(link.url)
print(link.token)
# https://8080-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/
# sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
```

TypeScript

```
const link = await sandboxes.createLink({ sandboxId, port: 8080, ttlSeconds: 3600 });
const answer = await fetch(link.url, { headers: { "Pethost-Token": link.token } });
console.log(answer.status);
```

Go

```
link, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{
	SandboxID:  id,
	Target:     sandboxes.CreateLinkPort(8080),
	TTLSeconds: 3600,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(link.URL)
fmt.Println(link.Token)
```

Rust

```
let link = sandboxes
    .create_link(CreateLinkRequest {
        sandbox_id: id.clone(),
        target: Some(CreateLinkRequestTarget::Port(8080)),
        ttl_seconds: 3600,
    })
    .await?;
println!("{}", link.url);
println!("{}", link.token);
```

CLI

```
$ curl -H "$(pethost sandbox url api-dev 8080 --token | tail -1)" "$(pethost sandbox url api-dev 8080)"
Port 8080 is private: a request sends its token, which --token prints. A browser opens a public port: pethost sandbox ports e9bprbw1hovj6sw5 --open 8080
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
…
```

## O endereço de uma porta

O endereço de uma porta é `https://<port>-<sandbox id>.<server>`, em que o servidor é aquele em que o sandbox roda, como `https://5173-k7f3q2xy0a1b2c3d.sbx1.sandboxes.pethost.network`. Pegue-o da resposta (`PublicPort.url`, `Link.url`) em vez de montá-lo: um sandbox parado que inicia em outro servidor muda de endereço junto.

A porta 443 fala HTTP/1.1 e HTTP/2, WebSockets incluídos, com um certificado que já está lá; a porta 80 responde com um redirecionamento para HTTPS e nada mais. As portas de um sandbox atendem 896 requisições ao mesmo tempo. O endereço de todo sandbox fica sob um mesmo domínio, então o servidor tira o `Domain` de um cookie que uma resposta define: dê aos cookies de um app o prefixo `__Host-`, que os prende ao endereço do próprio app.

## Pública ou privada

Uma porta pública responde a qualquer um que tenha o endereço: é disso que a aba de um navegador, uma imagem ou um WebSocket precisam, já que não podem enviar um cabeçalho. Uma porta privada é verificada antes de tudo: uma requisição sem o token dela, ou com o de outra porta, recebe 401 antes de acordar o sandbox. O servidor tira o cabeçalho, e o resto da requisição chega ao seu programa como foi enviado, `Authorization` e `Cookie` incluídos. Ele responde CORS para qualquer origem, então uma página sua pode fazer `fetch` na porta com um token que ela guarda. O token de conexão do sandbox é root lá dentro e não abre nenhuma porta: o token de uma porta é o que se entrega a uma página.

Para abrir uma porta privada no seu próprio navegador, encaminhe-a por SSH: `ssh -L 8080:localhost:8080 <sandbox id>@<server> -p 2222`, depois abra `http://localhost:8080`. [SSH](https://pethost.dev/pt/docs/sandboxes/ssh/) diz como entrar.

## Previews que dormem

Uma requisição à porta de um sandbox pausado o acorda: o servidor de desenvolvimento continua rodando, com o que tinha na memória, e a primeira resposta vem em cerca de 0,2 s. Assim, o preview de uma branch ou do trabalho de um agente pode pausar minutos depois da última visita e custar 30% do preço rodando até a próxima:

- **Salve o app como template** com as dependências instaladas, para um novo preview iniciar em cerca de 0,22 s ([templates](https://pethost.dev/pt/docs/sandboxes/templates/)).
- **Inicie-o com a porta pública** e o servidor de desenvolvimento rodando, iniciado com `wait_for_port`.
- **Faça-o pausar cedo**, com `pause_after_idle_seconds` `120`, e desative o timer de parada (`0`), para que a próxima visita sempre o encontre pausado, e não parado.
- **Exclua-o** quando a branch for mesclada, ou deixe `delete_after_idle_seconds` fazer isso.

Um preview de tamanho SMALL visitado 10 vezes por dia custa cerca de US$ 4,26 por mês assim: a [cobrança](https://pethost.dev/pt/docs/sandboxes/billing/#examples) tem a conta. A porta de um sandbox parado responde 503, “stopped: resume it”, a não ser que o ciclo de vida dele diga `wake_when_stopped` ([ciclo de vida](https://pethost.dev/pt/docs/sandboxes/lifecycle/#wake-when-stopped)).

## Quando não funciona

- **401 de uma porta:** ela é privada e a requisição não tinha token, tinha um expirado ou o de outra porta. Torne-a pública, ou envie `Pethost-Token` com um token novo para aquela porta.
- **Uma página de erro, ou nenhuma resposta:** nada escuta naquela porta no sandbox. Inicie o servidor com `wait_for_port` para saber que ele escuta, e confira a saída dele com `GetCommand`.
- **503 “stopped: resume it”:** o sandbox está parado. `ResumeSandbox` o inicia, sem os processos: inicie o servidor de novo, ou mantenha os previews pausados em vez de parados.
- **`wait_for_port` respondeu depois de 45 s sem porta:** o servidor não escutou a tempo, ou escuta em outra porta. Leia a saída dele.
- **403 “Blocked request. This host is not allowed.”:** um servidor de desenvolvimento do Vite verifica o cabeçalho `Host`, e o endereço da porta é novo para ele. Dê a ele `server: { allowedHosts: true }` no `vite.config.js`, ou o host do endereço nessa lista.
- **Um login não se mantém:** o app definiu um cookie para um domínio mais amplo, que o servidor remove. Use um cookie `__Host-`.

## Perguntas

### Como consigo uma URL pública para uma porta de um sandbox?

Adicione a porta a `settings.ingress.public_ports` com `UpdateSandbox`, ou rode `pethost sandbox ports <id> --open <port>`. O endereço dela é `https://<port>-<sandbox id>.<server>`.

### Posso proteger uma porta com senha?

Uma porta privada só responde a requisições com o token dela no cabeçalho `Pethost-Token`, que `CreateLink` cria. Para um navegador, encaminhe-a com `ssh -L`.

### WebSockets funcionam?

Sim, em portas públicas e nas privadas a partir de um cliente que envia o cabeçalho, por HTTP/1.1 e HTTP/2.

### Uma visita acorda um sandbox pausado?

Sim: em cerca de 0,2 s, com o servidor ainda rodando. Um parado só acorda assim com `wake_when_stopped`.

### Quantas portas podem ser públicas?

Até 20 por sandbox. Qualquer outra porta é alcançável com um token.

[AnteriorRode comandos e edite arquivos em um sandbox](https://pethost.dev/pt/docs/sandboxes/commands-and-files/) [PróximaRode Claude Code, Codex e OpenCode em um sandbox](https://pethost.dev/pt/docs/sandboxes/coding-agents/)

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