Documentation Agent Sandboxes · Tâches
Ports et prévisualisations : les URL d’une sandbox
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.
wait_for_portsurRunCommand: 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 deCreateLinkavecport: pour les programmes, curl et lefetchd’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.
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
const server = await sandboxes.runCommand({
sandboxId,
command: "python3 -m http.server 5173",
waitForPort: 5173,
});
console.log(server.state, server.commandId); // RUNNING
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
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
$ 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.
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
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);
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)
}
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);
}
$ pethost sandbox ports api-dev --open 5173
5173 https://5173-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network
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.
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…
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);
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)
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);
$ 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_secondsle 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-Tokenavec 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_portpour savoir qu’il écoute, et lisez sa sortie avecGetCommand. - 503 « stopped: resume it » : la sandbox est arrêtée.
ResumeSandboxla démarre, sans ses processus : redémarrez le serveur, ou gardez les prévisualisations en pause plutôt qu’arrêtées. wait_for_porta 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-luiserver: { allowedHosts: true }dansvite.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.