Français
Menu de la documentation

Documentation Agent Sandboxes · Tâches

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

Mis à jour le · 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 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).
  • 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 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).

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.

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