---
title: "Puertos y previsualizaciones: las URL de un sandbox | Pethost Agent Sandboxes"
description: "Dale a cualquier puerto de un sandbox una dirección HTTPS, pública o detrás de un token, espera a que escuche un servidor y crea previsualizaciones que duermen."
---

[Documentación de Agent Sandboxes](https://pethost.dev/es/docs/sandboxes/) · Tareas

# Puertos y previsualizaciones: las URL de un sandbox

Actualizado 22 de noviembre de 2026 · 7 min de lectura

Cada puerto de un sandbox tiene su propia dirección HTTPS, `https://<port>-<sandbox id>.<server>`. Haz público un puerto y cualquiera puede abrirlo; déjalo privado y solo responde a las peticiones que llevan su token. Una petición al puerto de un sandbox en pausa lo despierta, así que una previsualización puede dormir entre visitas.

**En resumen**

- **`wait_for_port`** en `RunCommand`: la llamada responde cuando tu servidor escucha, mientras sigue en ejecución.
- **Los puertos públicos** (`settings.ingress.public_ports`, hasta 20) responden a cualquiera, también a un navegador.
- **Los puertos privados** responden a las peticiones con `Pethost-Token: <token>`, que da `CreateLink` con `port`: para programas, curl y el `fetch` de una página.
- **Una visita despierta un sandbox en pausa** en unos 0,2 s, con su servidor donde estaba.

### Step 1: Inicia un servidor y espera a su puerto

Inicia el servidor con `wait_for_port`. La llamada responde en cuanto algo escucha en ese puerto, dentro de `wait_seconds`, y el servidor sigue en ejecución. También se llega a un servidor que escucha en `localhost`.

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: Haz público el puerto

Un puerto público está en los ajustes `ingress` del sandbox. `UpdateSandbox` reemplaza el grupo entero, así que envía cada puerto que deba seguir público; la respuesta trae la `url` de cada uno.

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}]}}}
```

Un puerto puede ser público desde el principio: pasa el mismo `ingress` a `CreateSandbox`, o `--public-port 5173` a `pethost sandbox new`.

### Step 3: O déjalo privado, detrás de un token

Cualquier puerto que no sea público solo responde a una petición con la cabecera `Pethost-Token`. `CreateLink` con `port` responde la dirección del puerto y un token solo para ese puerto, que caduca tras una hora salvo que `ttl_seconds` diga otra cosa. Aquí un segundo servidor, iniciado como en el primer paso, escucha en el 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>
…
```

## La dirección de un puerto

La dirección de un puerto es `https://<port>-<sandbox id>.<server>`, donde el servidor es aquel en el que se ejecuta el sandbox, como `https://5173-k7f3q2xy0a1b2c3d.sbx1.sandboxes.pethost.network`. Tómala de la respuesta (`PublicPort.url`, `Link.url`) en vez de construirla: un sandbox detenido que se inicia en otro servidor cambia sus direcciones con él.

El puerto 443 habla HTTP/1.1 y HTTP/2, WebSockets incluidos, con un certificado que ya está ahí; el puerto 80 responde con una redirección a HTTPS y nada más. Los puertos de un sandbox atienden 896 peticiones a la vez. Las direcciones de todos los sandboxes están bajo un mismo dominio, así que el servidor quita el `Domain` de una cookie que fija una respuesta: dale a las cookies de una app el prefijo `__Host-`, que las limita a la propia dirección de la app.

## Público o privado

Un puerto público responde a cualquiera que tenga la dirección: es lo que necesitan una pestaña del navegador, una imagen o un WebSocket, que no pueden enviar una cabecera. Un puerto privado se comprueba antes que nada: una petición sin su token, o con el de otro puerto, recibe un 401 antes de despertar el sandbox. El servidor quita la cabecera, y el resto de la petición llega a tu programa tal como se envió, `Authorization` y `Cookie` incluidas. Responde a CORS para cualquier origen, así que una página tuya puede hacer `fetch` al puerto con un token que tenga. El token de conexión del sandbox es root dentro de él y no abre ningún puerto: el token que hay que dar a una página es el de un puerto.

Para abrir un puerto privado en tu propio navegador, redirígelo por SSH: `ssh -L 8080:localhost:8080 <sandbox id>@<server> -p 2222`, y abre `http://localhost:8080`. [SSH](https://pethost.dev/es/docs/sandboxes/ssh/) dice cómo iniciar sesión.

## Previsualizaciones que duermen

Una petición al puerto de un sandbox en pausa lo despierta: el servidor de desarrollo sigue en ejecución, con lo que tenía en memoria, y la primera respuesta llega en unos 0,2 s. Así, una previsualización de una rama o del trabajo de un agente puede pausarse minutos después de su última visita y costar el 30 % del precio en ejecución hasta la siguiente:

- **Guarda la app como plantilla** con sus dependencias instaladas, para que una previsualización nueva se inicie en unos 0,22 s ([plantillas](https://pethost.dev/es/docs/sandboxes/templates/)).
- **Iníciala con su puerto público** y su servidor de desarrollo en ejecución, iniciado con `wait_for_port`.
- **Páusala pronto**, con `pause_after_idle_seconds` a `120`, y desactiva el temporizador de detención (`0`), para que la siguiente visita siempre la encuentre en pausa y no detenida.
- **Elimínala** cuando se fusione la rama, o deja que lo haga `delete_after_idle_seconds`.

Una previsualización de tamaño SMALL visitada 10 veces al día cuesta así unos 4,26 US$ al mes: [facturación](https://pethost.dev/es/docs/sandboxes/billing/#examples) tiene la cuenta. El puerto de un sandbox detenido responde 503, “stopped: resume it”, salvo que su ciclo de vida diga `wake_when_stopped` ([ciclo de vida](https://pethost.dev/es/docs/sandboxes/lifecycle/#wake-when-stopped)).

## Cuando no funciona

- **Un 401 de un puerto:** es privado y la petición no llevaba token, llevaba uno caducado o el de otro puerto. Hazlo público, o envía `Pethost-Token` con un token nuevo para ese puerto.
- **Una página de error, o ninguna respuesta:** nada escucha en ese puerto dentro del sandbox. Inicia el servidor con `wait_for_port` para saber que escucha, y revisa su salida con `GetCommand`.
- **Un 503 “stopped: resume it”:** el sandbox está detenido. `ResumeSandbox` lo inicia, sin sus procesos: vuelve a iniciar el servidor, o deja las previsualizaciones en pausa en vez de detenidas.
- **`wait_for_port` respondió tras 45 s sin puerto:** el servidor no escuchó a tiempo, o escucha en otro puerto. Lee su salida.
- **Un 403 “Blocked request. This host is not allowed.”:** un servidor de desarrollo de Vite comprueba la cabecera `Host`, y la dirección del puerto es nueva para él. Dale `server: { allowedHosts: true }` en `vite.config.js`, o el host de la dirección en esa lista.
- **Un inicio de sesión no se mantiene:** la app fijó una cookie para un dominio más amplio, que el servidor quita. Usa una cookie `__Host-`.

## Preguntas

### ¿Cómo consigo una URL pública para un puerto de un sandbox?

Agrega el puerto a `settings.ingress.public_ports` con `UpdateSandbox`, o ejecuta `pethost sandbox ports <id> --open <port>`. Su dirección es `https://<port>-<sandbox id>.<server>`.

### ¿Puedo proteger un puerto con una contraseña?

Un puerto privado solo responde a las peticiones con su token en la cabecera `Pethost-Token`, que crea `CreateLink`. Para un navegador, redirígelo con `ssh -L`.

### ¿Funcionan los WebSockets?

Sí, en los puertos públicos y en los privados desde un cliente que envíe la cabecera, por HTTP/1.1 y HTTP/2.

### ¿Una visita despierta un sandbox en pausa?

Sí: en unos 0,2 s, con su servidor aún en ejecución. Uno detenido solo despierta así con `wake_when_stopped`.

### ¿Cuántos puertos pueden ser públicos?

Hasta 20 por sandbox. Cualquier otro puerto es accesible con un token.

[AnteriorEjecuta comandos y edita archivos en un sandbox](https://pethost.dev/es/docs/sandboxes/commands-and-files/) [SiguienteEjecuta Claude Code, Codex y OpenCode en un sandbox](https://pethost.dev/es/docs/sandboxes/coding-agents/)

## Prueba Pethost Agent Sandboxes

Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.

[Empezar la prueba gratis](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Plantillas](https://pethost.dev/es/templates/)
- [Sobre nosotros](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/es/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Términos](https://pethost.dev/terms/)
- [Privacidad](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bases de datos

- [Postgres](https://pethost.dev/es/postgres/)
- [Valkey](https://pethost.dev/es/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/es/sandboxes/)
- [Precios](https://pethost.dev/es/sandboxes/#pricing)
- [Docs](https://pethost.dev/es/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparativas

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/es/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/es/blog/coolify-cloud-vs-dokploy-cloud/)
- [Precios de Railway vs Render vs Fly.io](https://pethost.dev/es/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hosting gestionado para Docker Compose](https://pethost.dev/es/blog/managed-docker-compose-hosting/)

Alternativas

- [Alternativas a Railway](https://pethost.dev/es/blog/railway-alternatives/)
- [Alternativas a Heroku](https://pethost.dev/es/blog/heroku-alternatives/)
- [Alternativas a Dokploy](https://pethost.dev/es/blog/dokploy-alternatives/)
- [Alternativas a Coolify](https://pethost.dev/es/blog/coolify-alternatives/)
- [Alternativas a Render](https://pethost.dev/es/blog/render-alternatives/)
- [Alternativas a Sliplane](https://pethost.dev/es/blog/sliplane-alternatives/)
