---
title: "Porty i podglądy: adresy URL sandboxa | Pethost Agent Sandboxes"
description: "Daj dowolnemu portowi sandboxa adres HTTPS, publiczny albo za tokenem, poczekaj, aż serwer deweloperski zacznie nasłuchiwać, i trzymaj podglądy, które śpią."
---

[Dokumentacja Agent Sandboxes](https://pethost.dev/pl/docs/sandboxes/) · Zadania

# Porty i podglądy: adresy URL sandboxa

Zaktualizowano 22 listopada 2026 · 6 min czytania

Każdy port sandboxa ma własny adres HTTPS, `https://<port>-<sandbox id>.<server>`. Udostępnij port publicznie, a każdy będzie mógł go otworzyć; zostaw go prywatnym, a odpowie tylko na żądania z jego tokenem. Żądanie do portu wstrzymanego sandboxa go budzi, więc podgląd może spać między wizytami.

**W skrócie**

- **`wait_for_port`** w `RunCommand`: wywołanie odpowiada, gdy twój serwer zacznie nasłuchiwać, a serwer działa dalej.
- **Publiczne porty** (`settings.ingress.public_ports`, do 20) odpowiadają każdemu, także przeglądarce.
- **Prywatne porty** odpowiadają na żądania z `Pethost-Token: <token>`, z `CreateLink` z `port`: dla programów, curl i `fetch` na stronie.
- **Wizyta budzi wstrzymany sandbox** w ok. 0,2 s, z serwerem tam, gdzie był.

### Step 1: Uruchom serwer i poczekaj na jego port

Uruchom serwer z `wait_for_port`. Wywołanie odpowiada, gdy tylko coś nasłuchuje na tym porcie, w ramach `wait_seconds`, a serwer działa dalej. Serwer nasłuchujący na `localhost` też jest osiągalny.

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: Udostępnij port publicznie

Publiczny port jest w ustawieniach `ingress` sandboxa. `UpdateSandbox` zastępuje całą grupę, więc wyślij każdy port, który ma zostać publiczny; odpowiedź ma `url` każdego z nich.

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

Port może być publiczny od początku: przekaż to samo `ingress` do `CreateSandbox` albo `--public-port 5173` do `pethost sandbox new`.

### Step 3: Albo zostaw go prywatnym, za tokenem

Każdy port, który nie jest publiczny, odpowiada tylko na żądanie z nagłówkiem `Pethost-Token`. `CreateLink` z `port` zwraca adres portu i token tylko dla tego portu, który wygasa po godzinie, chyba że `ttl_seconds` mówi inaczej. Tutaj drugi serwer, uruchomiony jak w pierwszym kroku, nasłuchuje 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>
…
```

## Adres portu

Adres portu to `https://<port>-<sandbox id>.<server>`, gdzie serwer to ten, na którym działa sandbox, np. `https://5173-k7f3q2xy0a1b2c3d.sbx1.sandboxes.pethost.network`. Bierz go z odpowiedzi (`PublicPort.url`, `Link.url`), zamiast go składać: zatrzymany sandbox, który wystartuje na innym serwerze, zmienia razem z nim swoje adresy.

Port 443 mówi HTTP/1.1 i HTTP/2, łącznie z WebSocketami, z gotowym certyfikatem; port 80 odpowiada tylko przekierowaniem na HTTPS. Porty sandboxa obsługują 896 żądań naraz. Adresy wszystkich sandboxów są w jednej domenie, więc serwer zdejmuje `Domain` z ciasteczka ustawionego przez odpowiedź: daj ciasteczkom aplikacji prefiks `__Host-`, który trzyma je przy własnym adresie aplikacji.

## Publiczny czy prywatny

Publiczny port odpowiada każdemu, kto ma adres: tego potrzebuje karta przeglądarki, obrazek czy WebSocket, bo nie mogą wysłać nagłówka. Prywatny port jest sprawdzany przed wszystkim innym: żądanie bez jego tokena albo z tokenem innego portu dostaje 401, zanim obudzi sandbox. Serwer zdejmuje nagłówek, a reszta żądania dociera do twojego programu taka, jak została wysłana, łącznie z `Authorization` i `Cookie`. Odpowiada na CORS dla dowolnego originu, więc twoja strona może zrobić `fetch` do portu z tokenem, który ma. Token połączenia sandboxa daje w nim roota i nie otwiera żadnego portu: stronie daje się token portu.

Żeby otworzyć prywatny port we własnej przeglądarce, przekieruj go przez SSH: `ssh -L 8080:localhost:8080 <sandbox id>@<server> -p 2222`, a potem otwórz `http://localhost:8080`. [SSH](https://pethost.dev/pl/docs/sandboxes/ssh/) mówi, jak się zalogować.

## Podglądy, które śpią

Żądanie do portu wstrzymanego sandboxa go budzi: serwer deweloperski wciąż działa, z tym, co miał w pamięci, a pierwsza odpowiedź przychodzi w ok. 0,2 s. Dlatego podgląd brancha albo pracy agenta może się wstrzymać kilka minut po ostatniej wizycie i kosztować 30% ceny działania aż do następnej:

- **Zapisz aplikację jako szablon** z zainstalowanymi zależnościami, żeby nowy podgląd startował w ok. 0,22 s ([szablony](https://pethost.dev/pl/docs/sandboxes/templates/)).
- **Uruchamiaj go z publicznym portem** i działającym serwerem deweloperskim, uruchomionym z `wait_for_port`.
- **Wstrzymuj go wcześnie**, z `pause_after_idle_seconds` `120`, i wyłącz licznik zatrzymania (`0`), żeby następna wizyta zawsze zastała go wstrzymanego, a nie zatrzymanego.
- **Usuń go**, gdy branch zostanie zmergowany, albo zostaw to `delete_after_idle_seconds`.

Podgląd w rozmiarze SMALL odwiedzany 10 razy dziennie kosztuje tak ok. 4,26 $ miesięcznie: wyliczenie jest w [rozliczeniach](https://pethost.dev/pl/docs/sandboxes/billing/#examples). Port zatrzymanego sandboxa odpowiada 503, „stopped: resume it”, chyba że jego cykl życia ma `wake_when_stopped` ([cykl życia](https://pethost.dev/pl/docs/sandboxes/lifecycle/#wake-when-stopped)).

## Gdy to nie działa

- **401 z portu:** port jest prywatny, a żądanie nie miało tokena, miało wygasły albo token innego portu. Udostępnij go publicznie albo wyślij `Pethost-Token` ze świeżym tokenem dla tego portu.
- **Strona błędu albo brak odpowiedzi:** nic nie nasłuchuje na tym porcie w sandboxie. Uruchom serwer z `wait_for_port`, żeby wiedzieć, że nasłuchuje, i sprawdź jego wyjście przez `GetCommand`.
- **503 „stopped: resume it”:** sandbox jest zatrzymany. `ResumeSandbox` go uruchamia, ale bez procesów: uruchom serwer ponownie albo trzymaj podglądy wstrzymane, a nie zatrzymane.
- **`wait_for_port` odpowiedziało po 45 s bez portu:** serwer nie zaczął nasłuchiwać na czas albo nasłuchuje na innym porcie. Przeczytaj jego wyjście.
- **403 „Blocked request. This host is not allowed.”:** serwer deweloperski Vite sprawdza nagłówek `Host`, a adres portu jest dla niego nowy. Daj mu `server: { allowedHosts: true }` w `vite.config.js` albo host adresu na tej liście.
- **Logowanie się nie trzyma:** aplikacja ustawiła ciasteczko dla szerszej domeny, a serwer je zdejmuje. Użyj ciasteczka `__Host-`.

## Pytania

### Jak dostać publiczny URL dla portu w sandboxie?

Dodaj port do `settings.ingress.public_ports` przez `UpdateSandbox` albo uruchom `pethost sandbox ports <id> --open <port>`. Jego adres to `https://<port>-<sandbox id>.<server>`.

### Czy mogę zabezpieczyć port hasłem?

Prywatny port odpowiada tylko na żądania z jego tokenem w nagłówku `Pethost-Token`, który tworzy `CreateLink`. Dla przeglądarki przekieruj go przez `ssh -L`.

### Czy działają WebSockety?

Tak, na publicznych portach i na prywatnych z klienta, który wysyła nagłówek, przez HTTP/1.1 i HTTP/2.

### Czy wizyta budzi wstrzymany sandbox?

Tak: w ok. 0,2 s, z wciąż działającym serwerem. Zatrzymany budzi się tak tylko z `wake_when_stopped`.

### Ile portów może być publicznych?

Do 20 na sandbox. Każdy inny port jest osiągalny z tokenem.

[PoprzedniaUruchamianie poleceń i edycja plików w sandboxie](https://pethost.dev/pl/docs/sandboxes/commands-and-files/) [NastępnaUruchamianie Claude Code, Codex i OpenCode w sandboxie](https://pethost.dev/pl/docs/sandboxes/coding-agents/)

## Wypróbuj Pethost Agent Sandboxes

Okres próbny na 7 dni z 1 $ zużycia i 4 vCPU, z kartą. Potem plan od 20 $ miesięcznie, który zawiera tyle samo zużycia.

[Zacznij okres próbny](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Szablony](https://pethost.dev/pl/templates/)
- [O nas](https://pethost.dev/about/)
- [Dokumentacja](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/pl/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Regulamin](https://pethost.dev/terms/)
- [Prywatność](https://pethost.dev/privacy/)
- [Zwroty](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bazy danych

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

Agent Sandboxes

- [Sandboxy](https://pethost.dev/pl/sandboxes/)
- [Cennik](https://pethost.dev/pl/sandboxes/#pricing)
- [Dokumentacja](https://pethost.dev/pl/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Porównania

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/pl/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/pl/blog/coolify-cloud-vs-dokploy-cloud/)
- [Cennik Railway vs Render vs Fly.io](https://pethost.dev/pl/blog/railway-vs-render-vs-fly-io-pricing/)
- [Zarządzany hosting Docker Compose](https://pethost.dev/pl/blog/managed-docker-compose-hosting/)

Alternatywy

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