Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Aufgaben

Ports und Vorschauen: die URLs einer Sandbox

Aktualisiert · 6 Min. Lesezeit

Jeder Port einer Sandbox hat eine eigene HTTPS-Adresse, https://<port>-<sandbox id>.<server>. Mach einen Port öffentlich, und alle können ihn öffnen; lass ihn privat, und er beantwortet nur Requests, die sein Token tragen. Ein Request an den Port einer pausierten Sandbox weckt sie, also kann eine Vorschau zwischen Besuchen schlafen.

Kurz gesagt
  • wait_for_port bei RunCommand: Der Aufruf antwortet, sobald dein Server lauscht, während er weiterläuft.
  • Öffentliche Ports (settings.ingress.public_ports, bis zu 20) antworten allen, auch einem Browser.
  • Private Ports beantworten Requests mit Pethost-Token: <token>, von CreateLink mit port: für Programme, curl und das fetch einer Seite.
  • Ein Besuch weckt eine pausierte Sandbox in etwa 0,2 s, ihren Server dort, wo er war.

Step 1: Server starten und auf seinen Port warten

Starte den Server mit wait_for_port. Der Aufruf antwortet, sobald etwas auf diesem Port lauscht, innerhalb von wait_seconds, und der Server läuft weiter. Auch ein Server, der auf localhost lauscht, wird erreicht.

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: Port öffentlich machen

Ein öffentlicher Port steht in den ingress-Einstellungen der Sandbox. UpdateSandbox ersetzt die ganze Gruppe, also schick jeden Port, der öffentlich bleiben soll; die Antwort hat die url jedes einzelnen.

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

Ein Port kann von Anfang an öffentlich sein: Gib dasselbe ingress an CreateSandbox oder --public-port 5173 an pethost sandbox new.

Step 3: Oder privat lassen, hinter einem Token

Jeder Port, der nicht öffentlich ist, beantwortet nur einen Request mit dem Header Pethost-Token. CreateLink mit port antwortet mit der Adresse des Ports und einem Token nur für diesen Port, das nach einer Stunde abläuft, außer ttl_seconds sagt etwas anderes. Hier lauscht ein zweiter Server, gestartet wie im ersten Schritt, auf 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>
…

Die Adresse eines Ports

Die Adresse eines Ports ist https://<port>-<sandbox id>.<server>, wobei der Server der ist, auf dem die Sandbox läuft, etwa https://5173-k7f3q2xy0a1b2c3d.sbx1.sandboxes.pethost.network. Nimm sie aus der Antwort (PublicPort.url, Link.url), statt sie zusammenzubauen: Eine gestoppte Sandbox, die auf einem anderen Server startet, ändert ihre Adressen mit.

Port 443 spricht HTTP/1.1 und HTTP/2, WebSockets eingeschlossen, mit einem Zertifikat, das schon da ist; Port 80 antwortet mit einer Weiterleitung auf HTTPS und sonst nichts. Die Ports einer Sandbox bedienen 896 Requests gleichzeitig. Die Adresse jeder Sandbox liegt unter einer Domain, also nimmt der Server die Domain von einem Cookie, das eine Antwort setzt: Gib den Cookies einer App das Präfix __Host-, das sie auf die eigene Adresse der App beschränkt.

Öffentlich oder privat

Ein öffentlicher Port antwortet allen, die die Adresse haben: Das braucht ein Browser-Tab, ein Bild oder ein WebSocket, denn sie können keinen Header schicken. Ein privater Port wird vor allem anderen geprüft: Ein Request ohne sein Token, oder mit dem eines anderen Ports, wird mit 401 beantwortet, bevor er die Sandbox weckt. Der Server nimmt den Header weg, und der Rest des Requests erreicht dein Programm, wie er geschickt wurde, Authorization und Cookie eingeschlossen. Er beantwortet CORS für jeden Origin, also darf eine Seite von dir den Port mit einem Token, das sie hält, per fetch aufrufen. Das Verbindungs-Token der Sandbox ist root darin und öffnet keinen Port: Das Token eines Ports ist das, das du einer Seite gibst.

Um einen privaten Port in deinem eigenen Browser zu öffnen, leite ihn über SSH weiter: ssh -L 8080:localhost:8080 <sandbox id>@<server> -p 2222, dann öffne http://localhost:8080. SSH sagt, wie du dich anmeldest.

Vorschauen, die schlafen

Ein Request an den Port einer pausierten Sandbox weckt sie: Der Dev-Server läuft noch, mit dem, was er im RAM hatte, und die erste Antwort kommt in etwa 0,2 s. So kann die Vorschau eines Branches oder der Arbeit eines Agenten Minuten nach dem letzten Besuch pausieren und bis zum nächsten 30 % des Preises im Betrieb kosten:

  • Speichere die App als Vorlage mit installierten Abhängigkeiten, damit eine neue Vorschau in etwa 0,22 s startet (Vorlagen).
  • Starte sie mit öffentlichem Port und laufendem Dev-Server, gestartet mit wait_for_port.
  • Pausier sie früh, mit pause_after_idle_seconds 120, und schalt den Stopp-Timer ab (0), damit der nächste Besuch sie immer pausiert und nicht gestoppt findet.
  • Lösch sie, wenn der Branch gemergt ist, oder überlass es delete_after_idle_seconds.

Eine Vorschau der Größe SMALL mit 10 Besuchen am Tag kostet so etwa 4,26 $ im Monat: Abrechnung hat die Rechnung. Der Port einer gestoppten Sandbox antwortet 503, „stopped: resume it“, außer ihr Lebenszyklus sagt wake_when_stopped (Lebenszyklus).

Wenn es nicht funktioniert

  • 401 von einem Port: Er ist privat, und der Request hatte kein Token, ein abgelaufenes oder das eines anderen Ports. Mach ihn öffentlich, oder schick Pethost-Token mit einem frischen Token für diesen Port.
  • Eine Fehlerseite oder keine Antwort: Auf diesem Port lauscht nichts in der Sandbox. Starte den Server mit wait_for_port, um zu wissen, dass er lauscht, und prüf seine Ausgabe mit GetCommand.
  • 503 „stopped: resume it“: Die Sandbox ist gestoppt. ResumeSandbox startet sie, ihre Prozesse sind weg: Starte den Server neu, oder halte Vorschauen pausiert statt gestoppt.
  • wait_for_port hat nach 45 s ohne Port geantwortet: Der Server hat nicht rechtzeitig gelauscht, oder er lauscht auf einem anderen Port. Lies seine Ausgabe.
  • 403 „Blocked request. This host is not allowed.“: Ein Vite-Dev-Server prüft den Host-Header, und die Adresse des Ports ist ihm neu. Gib ihm server: { allowedHosts: true } in vite.config.js, oder den Host der Adresse in dieser Liste.
  • Eine Anmeldung bleibt nicht bestehen: Die App hat ein Cookie für eine weitere Domain gesetzt, die der Server wegnimmt. Nimm ein __Host--Cookie.

Fragen

Wie bekomme ich eine öffentliche URL für einen Port in einer Sandbox?

Füg den Port mit UpdateSandbox zu settings.ingress.public_ports hinzu, oder führ pethost sandbox ports <id> --open <port> aus. Seine Adresse ist https://<port>-<sandbox id>.<server>.

Kann ich einen Port mit einem Passwort schützen?

Ein privater Port beantwortet nur Requests mit seinem Token im Header Pethost-Token, das CreateLink erstellt. Für einen Browser leite ihn mit ssh -L weiter.

Funktionieren WebSockets?

Ja, auf öffentlichen Ports und auf privaten von einem Client, der den Header schickt, über HTTP/1.1 und HTTP/2.

Weckt ein Besuch eine pausierte Sandbox?

Ja: in etwa 0,2 s, mit ihrem Server, der noch läuft. Eine gestoppte wacht so nur mit wake_when_stopped auf.

Wie viele Ports können öffentlich sein?

Bis zu 20 pro Sandbox. Jeder andere Port ist mit einem Token erreichbar.

Pethost Agent Sandboxes ausprobieren

Eine Testphase von 7 Tagen mit 1 $ Verbrauch und 4 vCPUs, mit Karte. Danach ein Tarif ab 20 $ im Monat, der genauso viel Verbrauch enthält.

Testphase starten