---
title: "Ports et prévisualisations : les URL d’une sandbox | Pethost Agent Sandboxes"
description: "Donnez à tout port d’une sandbox une adresse HTTPS, publique ou derrière un token, attendez qu’un serveur écoute, et lancez des prévisualisations qui dorment."
---

[Documentation Agent Sandboxes](https://pethost.dev/fr/docs/sandboxes/) · Tâches

# Ports et prévisualisations : les URL d’une sandbox

Mis à jour le 22 novembre 2026 · 7 min de lecture

Chaque port d’une sandbox a sa propre adresse HTTPS, `https://<port>-<sandbox id>.<server>`. Rendez un port public et tout le monde peut l’ouvrir ; laissez-le privé et il ne répond qu’aux requêtes qui portent son token. Une requête vers le port d’une sandbox en pause la réveille : une prévisualisation peut donc dormir entre deux visites.

**En bref**

- **`wait_for_port`** sur `RunCommand` : l’appel répond une fois que votre serveur écoute, pendant qu’il continue de tourner.
- **Les ports publics** (`settings.ingress.public_ports`, jusqu’à 20) répondent à tout le monde, navigateur compris.
- **Les ports privés** répondent aux requêtes avec `Pethost-Token: <token>`, issu de `CreateLink` avec `port` : pour les programmes, curl et le `fetch` d’une page.
- **Une visite réveille une sandbox en pause** en 0,2 s environ, avec son serveur là où il en était.

### Step 1: Démarrez un serveur et attendez son port

Démarrez le serveur avec `wait_for_port`. L’appel répond dès que quelque chose écoute sur ce port, dans la limite de `wait_seconds`, et le serveur continue de tourner. Un serveur qui écoute sur `localhost` est joint aussi.

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: Rendez le port public

Un port public se règle dans les paramètres `ingress` de la sandbox. `UpdateSandbox` remplace tout le groupe : envoyez donc chaque port qui doit rester public ; la réponse donne l’`url` de chacun.

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 port peut être public dès le départ : passez le même `ingress` à `CreateSandbox`, ou `--public-port 5173` à `pethost sandbox new`.

### Step 3: Ou gardez-le privé, derrière un token

Tout port qui n’est pas public ne répond qu’à une requête avec l’en-tête `Pethost-Token`. `CreateLink` avec `port` répond avec l’adresse du port et un token pour ce seul port, qui expire au bout d’une heure sauf si `ttl_seconds` dit autre chose. Ici, un second serveur, démarré comme à la première étape, écoute sur 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>
…
```

## L’adresse d’un port

L’adresse d’un port est `https://<port>-<sandbox id>.<server>`, où le serveur est celui sur lequel tourne la sandbox, par exemple `https://5173-k7f3q2xy0a1b2c3d.sbx1.sandboxes.pethost.network`. Prenez-la dans la réponse (`PublicPort.url`, `Link.url`) plutôt que de la construire : une sandbox arrêtée qui démarre sur un autre serveur change d’adresses avec lui.

Le port 443 parle HTTP/1.1 et HTTP/2, WebSockets comprises, avec un certificat déjà en place ; le port 80 répond par une redirection vers HTTPS et rien d’autre. Les ports d’une sandbox servent 896 requêtes en même temps. Les adresses de toutes les sandboxes sont sous un même domaine : le serveur retire donc le `Domain` d’un cookie que pose une réponse. Donnez aux cookies d’une application le préfixe `__Host-`, qui les tient à l’adresse propre de l’application.

## Public ou privé

Un port public répond à quiconque a l’adresse : c’est ce qu’il faut à un onglet de navigateur, à une image ou à une WebSocket, qui ne peuvent pas envoyer d’en-tête. Un port privé est vérifié avant tout le reste : une requête sans son token, ou avec celui d’un autre port, reçoit un 401 avant de réveiller la sandbox. Le serveur retire l’en-tête, et le reste de la requête arrive à votre programme tel qu’il a été envoyé, `Authorization` et `Cookie` compris. Il répond au CORS pour toute origine : une page à vous peut donc faire un `fetch` vers le port avec un token qu’elle détient. Le token de connexion de la sandbox donne root à l’intérieur et n’ouvre aucun port : c’est le token d’un port qu’il faut donner à une page.

Pour ouvrir un port privé dans votre propre navigateur, redirigez-le par SSH : `ssh -L 8080:localhost:8080 <sandbox id>@<server> -p 2222`, puis ouvrez `http://localhost:8080`. [SSH](https://pethost.dev/fr/docs/sandboxes/ssh/) dit comment se connecter.

## Des prévisualisations qui dorment

Une requête vers le port d’une sandbox en pause la réveille : le serveur de développement tourne toujours, avec ce qu’il avait en mémoire, et la première réponse arrive en 0,2 s environ. La prévisualisation d’une branche ou du travail d’un agent peut donc se mettre en pause quelques minutes après sa dernière visite et coûter 30 % du prix d’exécution jusqu’à la suivante :

- **Enregistrez l’application comme template** avec ses dépendances installées, pour qu’une nouvelle prévisualisation démarre en 0,22 s environ ([templates](https://pethost.dev/fr/docs/sandboxes/templates/)).
- **Démarrez-la avec son port public** et son serveur de développement en marche, lancé avec `wait_for_port`.
- **Mettez-la en pause tôt**, avec `pause_after_idle_seconds` à `120`, et désactivez le délai d’arrêt (`0`), pour que la visite suivante la trouve toujours en pause plutôt qu’arrêtée.
- **Supprimez-la** quand la branche est fusionnée, ou laissez `delete_after_idle_seconds` le faire.

Une prévisualisation de taille SMALL visitée 10 fois par jour coûte ainsi environ 4,26 $ par mois : la [facturation](https://pethost.dev/fr/docs/sandboxes/billing/#examples) donne le calcul. Le port d’une sandbox arrêtée répond 503, « stopped: resume it », sauf si son cycle de vie dit `wake_when_stopped` ([cycle de vie](https://pethost.dev/fr/docs/sandboxes/lifecycle/#wake-when-stopped)).

## Quand ça ne marche pas

- **401 depuis un port :** il est privé et la requête n’avait pas de token, un token expiré, ou celui d’un autre port. Rendez-le public, ou envoyez `Pethost-Token` avec un token neuf pour ce port.
- **Une page d’erreur, ou aucune réponse :** rien n’écoute sur ce port dans la sandbox. Démarrez le serveur avec `wait_for_port` pour savoir qu’il écoute, et lisez sa sortie avec `GetCommand`.
- **503 « stopped: resume it » :** la sandbox est arrêtée. `ResumeSandbox` la démarre, sans ses processus : redémarrez le serveur, ou gardez les prévisualisations en pause plutôt qu’arrêtées.
- **`wait_for_port` a répondu au bout de 45 s sans port :** le serveur n’a pas écouté à temps, ou écoute sur un autre port. Lisez sa sortie.
- **403 « Blocked request. This host is not allowed. » :** un serveur de développement Vite vérifie l’en-tête `Host`, et l’adresse du port lui est inconnue. Donnez-lui `server: { allowedHosts: true }` dans `vite.config.js`, ou l’hôte de l’adresse dans cette liste.
- **Une connexion ne tient pas :** l’application a posé un cookie pour un domaine plus large, que le serveur retire. Utilisez un cookie `__Host-`.

## Questions

### Comment obtenir une URL publique pour un port d’une sandbox ?

Ajoutez le port à `settings.ingress.public_ports` avec `UpdateSandbox`, ou lancez `pethost sandbox ports <id> --open <port>`. Son adresse est `https://<port>-<sandbox id>.<server>`.

### Puis-je protéger un port par un mot de passe ?

Un port privé ne répond qu’aux requêtes qui portent son token dans l’en-tête `Pethost-Token`, que crée `CreateLink`. Pour un navigateur, redirigez-le avec `ssh -L`.

### Les WebSockets marchent-elles ?

Oui, sur les ports publics, et sur les ports privés depuis un client qui envoie l’en-tête, en HTTP/1.1 et HTTP/2.

### Une visite réveille-t-elle une sandbox en pause ?

Oui : en 0,2 s environ, avec son serveur toujours en marche. Une sandbox arrêtée ne se réveille ainsi qu’avec `wake_when_stopped`.

### Combien de ports peuvent être publics ?

Jusqu’à 20 par sandbox. Tout autre port est joignable avec un token.

[PrécédentLancer des commandes et modifier des fichiers dans une sandbox](https://pethost.dev/fr/docs/sandboxes/commands-and-files/) [SuivantFaire tourner Claude Code, Codex et OpenCode dans une sandbox](https://pethost.dev/fr/docs/sandboxes/coding-agents/)

## Essayez Pethost Agent Sandboxes

Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.

[Démarrer l’essai gratuit](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/fr/templates/)
- [À propos](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/fr/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Conditions](https://pethost.dev/terms/)
- [Confidentialité](https://pethost.dev/privacy/)
- [Remboursements](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bases de données

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

Agent Sandboxes

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

Comparatifs

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/fr/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/fr/blog/coolify-cloud-vs-dokploy-cloud/)
- [Tarifs Railway vs Render vs Fly.io](https://pethost.dev/fr/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hébergement Docker Compose managé](https://pethost.dev/fr/blog/managed-docker-compose-hosting/)

Alternatives

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