Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Zadania

Porty i podglądy: adresy URL sandboxa

Zaktualizowano · 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 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).
  • 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. Port zatrzymanego sandboxa odpowiada 503, „stopped: resume it”, chyba że jego cykl życia ma wake_when_stopped (cykl życia).

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.

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