---
title: "Ports und Vorschauen: die URLs einer Sandbox | Pethost Agent Sandboxes"
description: "Gib jedem Port einer Sandbox eine HTTPS-Adresse, öffentlich oder hinter einem Token, warte auf einen Dev-Server und lass Vorschauen zwischen Besuchen schlafen."
---

[Doku zu Agent Sandboxes](https://pethost.dev/de/docs/sandboxes/) · Aufgaben

# Ports und Vorschauen: die URLs einer Sandbox

Aktualisiert 22. November 2026 · 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](https://pethost.dev/de/docs/sandboxes/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](https://pethost.dev/de/docs/sandboxes/templates/)).
- **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](https://pethost.dev/de/docs/sandboxes/billing/#examples) hat die Rechnung. Der Port einer gestoppten Sandbox antwortet 503, „stopped: resume it“, außer ihr Lebenszyklus sagt `wake_when_stopped` ([Lebenszyklus](https://pethost.dev/de/docs/sandboxes/lifecycle/#wake-when-stopped)).

## 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.

[ZurückBefehle ausführen und Dateien bearbeiten in einer Sandbox](https://pethost.dev/de/docs/sandboxes/commands-and-files/) [WeiterClaude Code, Codex und OpenCode in einer Sandbox ausführen](https://pethost.dev/de/docs/sandboxes/coding-agents/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Vorlagen](https://pethost.dev/de/templates/)
- [Über uns](https://pethost.dev/about/)
- [Doku](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/de/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [AGB](https://pethost.dev/terms/)
- [Datenschutz](https://pethost.dev/privacy/)
- [Erstattung](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Datenbanken

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

Agent Sandboxes

- [Sandboxes](https://pethost.dev/de/sandboxes/)
- [Preise](https://pethost.dev/de/sandboxes/#pricing)
- [Doku](https://pethost.dev/de/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Vergleiche

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

Alternativen

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