Documentation Agent Sandboxes · Premiers pas
Démarrage rapide : votre première sandbox
Votre première sandbox en quelques minutes : installez un SDK, créez un token d’API, créez une sandbox, lancez-y une commande, écrivez un fichier, ouvrez un port vers Internet, laissez-la se mettre en pause, et supprimez-la. Chaque étape est un appel, en Python, TypeScript, Go ou Rust, et les mêmes étapes suivent avec la CLI pethost.
- Un seul paquet : le SDK de Pethost que vous connaissez déjà, avec un client pour les sandboxes à côté :
pethost.sandboxes,pethost/sandboxes,github.com/pethost-dev/sdk/go/sandboxes,pethost::sandboxes. - Un seul token : un token d’API dans
PETHOST_TOKEN. Le client trouve seul le serveur de chaque sandbox et son token. - Un seul ID : chaque appel nomme sa sandbox par
sandbox_id. - Aucun ménage à faire à la main : une sandbox que vous oubliez se met en pause au bout de 5 minutes et s’arrête au bout de 30.
Installer un SDK
Le client des sandboxes fait partie du SDK de Pethost dans chaque langage : une seule installation vous donne les deux. Python 3.10, Node 22 (ou Bun, ou Deno), Go 1.26 et Rust 1.88 ou plus récents.
pip install pethost
npm install pethost # or: bun add pethost
deno add jsr:@pethost/sdk # Deno: import from "@pethost/sdk/sandboxes"
go get github.com/pethost-dev/sdk/go
cargo add pethost
cargo add tokio --features macros,rt-multi-thread,time
curl -fsSL https://pethost.dev/install.sh | sh # macOS, Linux
irm https://pethost.dev/install.ps1 | iex # Windows, in PowerShell
Créer un token d’API
Step 1: Créez un espace de travail Agent Sandboxes
Connectez-vous sur console.pethost.dev et créez un espace de travail en choisissant Agent Sandboxes. Le premier d’un nouveau compte commence par un essai gratuit : 7 jours avec 1 $ de consommation et 4 vCPU, une carte étant demandée.
Step 2: Créez-lui un token
Dans l’espace de travail, ouvrez Connecter un agent ou votre code et cliquez sur Créer un token d’API. Le token commence par pth_, n’atteint que cet espace de travail, et n’est affiché qu’une fois. Vos tokens sont listés, et révoqués, dans les Paramètres de votre compte.
Step 3: Donnez-le à votre programme
export PETHOST_TOKEN=pth_...
Le client Python et la CLI le lisent dans l’environnement ; les programmes ci-dessous le passent aux clients TypeScript, Go et Rust. Gardez-le hors de votre code : il agit en votre nom.
Créer une sandbox
Une sandbox démarre depuis un template. Le nôtre, base, est Ubuntu 24.04 avec Python, Node.js, Docker, trois agents de code et Chrome. CreateSandbox répond une fois la sandbox active, en 0,15 s environ côté serveur, plus votre aller-retour vers la console.
from pethost.sandboxes import Sandboxes
sandboxes = Sandboxes() # reads PETHOST_TOKEN
sandbox = sandboxes.create_sandbox("base")
print(sandbox.sandbox_id, sandbox.state.name) # 5a4c9z5zw58mvqww RUNNING
import { Sandboxes } from "pethost/sandboxes";
const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const sandbox = await sandboxes.createSandbox({ template: "base" });
const sandboxId = sandbox.sandboxId;
console.log(sandboxId, sandbox.state);
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/pethost-dev/sdk/go/sandboxes"
)
func main() {
ctx := context.Background()
client := sandboxes.NewClient(sandboxes.Config{Token: os.Getenv("PETHOST_TOKEN")})
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "base"})
if err != nil {
log.Fatal(err)
}
id := sandbox.SandboxID
fmt.Println(id, sandbox.State)
// The next steps go on here.
}
use pethost::sandboxes::{types::*, Client};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let sandboxes = Client::new(&std::env::var("PETHOST_TOKEN")?);
let sandbox = sandboxes
.create_sandbox(CreateSandboxRequest { template: "base".into(), ..Default::default() })
.await?;
let id = sandbox.sandbox_id.clone();
println!("{id} {:?}", sandbox.state);
// The next steps go on here.
Ok(())
}
curl -s https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
-H "Authorization: Bearer $PETHOST_TOKEN" -H "Content-Type: application/json" \
-d '{"template": "base"}'
# {"sandbox_id": "w86eeaozgndh3gj2", "state": "SANDBOX_STATE_RUNNING", "template": "base@17", …,
# "connection": {"url": "https://sbx1.sandboxes.pethost.network", "token": "…", …}}
Gardez l’ID : chaque autre appel nomme la sandbox par lui. Vous pouvez aussi donner à une sandbox un name, unique dans l’espace de travail, par lequel ListSandboxes la trouve.
Lancer une commande
RunCommand exécute une commande shell en tant qu’utilisateur user dans /home/user, et répond quand elle se termine, avec son code de sortie et les derniers 32 KiB de sa sortie. Une commande qui dure plus de 45 s répond RUNNING et continue : commandes et fichiers dit comment la suivre.
command = sandboxes.run_command(sandbox.sandbox_id, command="python3 -c 'print(6 * 7)'")
print(command.exit_code, command.stdout) # 0 42
const command = await sandboxes.runCommand({ sandboxId, command: "python3 -c 'print(6 * 7)'" });
console.log(command.exitCode, command.stdout); // 0 42
command, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: "python3 -c 'print(6 * 7)'"})
if err != nil {
log.Fatal(err)
}
fmt.Println(*command.ExitCode, command.Stdout) // 0 42
let command = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "python3 -c 'print(6 * 7)'".into(),
..Default::default()
})
.await?;
println!("{:?} {}", command.exit_code, command.stdout); // Some(0) 42
# URL and TOKEN: connection.url and connection.token of the create's answer
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"sandbox_id": "'"$ID"'", "command": "python3 -c '\''print(6 * 7)'\''"}'
# {"commandId": "efpe95t24evu", "state": "COMMAND_STATE_EXITED", "exitCode": 0, "stdout": "42\n", …}
La commande est allée au serveur de la sandbox, pas à la console. Le SDK a pris l’adresse du serveur et un token pour cette sandbox dans la réponse de la création, et en redemande de nouveaux seul quand ils expirent.
Écrire et lire un fichier
WriteFiles applique des changements dans l’ordre, en un appel : il écrit des fichiers entiers, en modifie un par remplacement exact, déplace et supprime. Les chemins sont absolus, ou relatifs à /home/user, et les dossiers manquants sont créés.
from pethost.sandboxes import FileChange, TextEdit
sandboxes.write_files(sandbox.sandbox_id, changes=[
FileChange(path="app/hello.py", text="print('hello')\n"),
FileChange(path="app/hello.py", edit=TextEdit(old_text="hello", new_text="hello, sandbox")),
])
print(sandboxes.read_file(sandbox.sandbox_id, path="app/hello.py").text) # print('hello, sandbox')
await sandboxes.writeFiles({
sandboxId,
changes: [
{ path: "app/hello.py", text: "print('hello')\n" },
{ path: "app/hello.py", edit: { oldText: "hello", newText: "hello, sandbox" } },
],
});
const file = await sandboxes.readFile({ sandboxId, path: "app/hello.py" });
console.log(file.text);
_, err = client.WriteFiles(ctx, &sandboxes.WriteFilesRequest{SandboxID: id, Changes: []sandboxes.FileChange{
{Path: "app/hello.py", Change: sandboxes.FileChangeText("print('hello')\n")},
{Path: "app/hello.py", Change: sandboxes.FileChangeEdit{OldText: "hello", NewText: "hello, sandbox"}},
}})
if err != nil {
log.Fatal(err)
}
file, err := client.ReadFile(ctx, &sandboxes.ReadFileRequest{SandboxID: id, Path: "app/hello.py"})
if err != nil {
log.Fatal(err)
}
if text, ok := file.Content.(sandboxes.FileText); ok {
fmt.Print(string(text))
}
let write = |change| FileChange { path: "app/hello.py".into(), change: Some(change), ..Default::default() };
sandboxes
.write_files(WriteFilesRequest {
sandbox_id: id.clone(),
changes: vec![
write(FileChangeChange::Text("print('hello')\n".into())),
write(FileChangeChange::Edit(TextEdit { old_text: "hello".into(), new_text: "hello, sandbox".into() })),
],
})
.await?;
let file = sandboxes
.read_file(ReadFileRequest { sandbox_id: id.clone(), path: "app/hello.py".into(), ..Default::default() })
.await?;
if let Some(FileContent::Text(text)) = file.content {
print!("{text}");
}
Un changement qui échoue arrête le lot, et la réponse dit combien ont été faits et pourquoi le suivant a échoué (failure) : une modification dont le old_text n’est pas dans le fichier, ou y est deux fois, ne change rien.
Ouvrir un port vers Internet
Démarrez un serveur avec wait_for_port : l’appel répond dès que quelque chose écoute sur le port, pendant que le serveur continue de tourner. Rendez ensuite le port public. Il reçoit sa propre adresse, https://<port>-<sandbox id>.<server>, que tout le monde peut ouvrir.
from pethost.sandboxes import Ingress, PublicPort, SandboxSettings
sandboxes.run_command(sandbox.sandbox_id, command="python3 -m http.server 8000", wait_for_port=8000)
sandbox = sandboxes.update_sandbox(
sandbox.sandbox_id,
settings=SandboxSettings(ingress=Ingress(public_ports=[PublicPort(port=8000)])),
)
print(sandbox.settings.ingress.public_ports[0].url)
# https://8000-5a4c9z5zw58mvqww.sbx1.sandboxes.pethost.network
await sandboxes.runCommand({ sandboxId, command: "python3 -m http.server 8000", waitForPort: 8000 });
const updated = await sandboxes.updateSandbox({
sandboxId,
settings: { ingress: { publicPorts: [{ port: 8000 }] } },
});
console.log(updated.settings?.ingress?.publicPorts[0]?.url);
_, err = client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: "python3 -m http.server 8000", WaitForPort: 8000})
if err != nil {
log.Fatal(err)
}
updated, err := client.UpdateSandbox(ctx, &sandboxes.UpdateSandboxRequest{SandboxID: id, Settings: &sandboxes.SandboxSettings{
Ingress: &sandboxes.Ingress{PublicPorts: []sandboxes.PublicPort{{Port: 8000}}},
}})
if err != nil {
log.Fatal(err)
}
fmt.Println(updated.Settings.Ingress.PublicPorts[0].URL)
sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "python3 -m http.server 8000".into(),
wait_for_port: 8000,
..Default::default()
})
.await?;
let ingress = Ingress { public_ports: vec![PublicPort { port: 8000, ..Default::default() }] };
let updated = sandboxes
.update_sandbox(UpdateSandboxRequest {
sandbox_id: id.clone(),
settings: Some(SandboxSettings { ingress: Some(ingress), ..Default::default() }),
..Default::default()
})
.await?;
if let Some(ingress) = updated.settings.and_then(|settings| settings.ingress) {
println!("{}", ingress.public_ports[0].url);
}
UpdateSandbox {"sandbox_id": "…", "settings": {"ingress": {"public_ports": [{"port": 8000}]}}}
Ouvrez l’adresse dans un navigateur, ou avec curl : la liste du dossier /home/user revient. Un port qui n’est pas public ne répond qu’aux requêtes qui portent un token pour lui : ports et prévisualisations.
La laisser se mettre en pause
Laissez la sandbox tranquille 5 minutes et elle se met en pause : sa mémoire, ses processus et son disque sont gardés sur son serveur, à 30 % du prix d’exécution. Le prochain appel, la prochaine connexion SSH ou requête vers son port la réveille en 0,1 s environ, là où elle en était. Ici, elle est mise en pause tout de suite, et le serveur web est toujours là après le réveil :
print(sandboxes.pause_sandbox(sandbox.sandbox_id).state.name) # PAUSED
check = sandboxes.run_command(sandbox.sandbox_id, command="curl -s -o /dev/null -w '%{http_code}' localhost:8000")
print(check.stdout) # 200: the server ran on through the pause
print(sandboxes.get_sandbox(sandbox.sandbox_id).state.name) # RUNNING
console.log((await sandboxes.pauseSandbox({ sandboxId })).state); // PAUSED
const check = await sandboxes.runCommand({
sandboxId,
command: "curl -s -o /dev/null -w '%{http_code}' localhost:8000",
});
console.log(check.stdout); // 200: the server ran on through the pause
console.log((await sandboxes.getSandbox({ sandboxId })).state); // RUNNING
paused, err := client.PauseSandbox(ctx, &sandboxes.PauseSandboxRequest{SandboxID: id})
if err != nil {
log.Fatal(err)
}
fmt.Println(paused.State) // PAUSED
check, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
SandboxID: id,
Command: "curl -s -o /dev/null -w '%{http_code}' localhost:8000",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(check.Stdout) // 200: the server ran on through the pause
let paused = sandboxes
.pause_sandbox(PauseSandboxRequest { sandbox_id: id.clone(), ..Default::default() })
.await?;
println!("{:?}", paused.state); // Paused
let check = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "curl -s -o /dev/null -w '%{http_code}' localhost:8000".into(),
..Default::default()
})
.await?;
println!("{}", check.stdout); // 200: the server ran on through the pause
PauseSandbox {"sandbox_id": "…"}
Après 30 minutes d’inactivité, elle s’arrête : ses processus prennent fin, et son disque part en stockage objet, où il coûte 0,03 $ par GiB et par mois de ce qu’il contient. ResumeSandbox la redémarre. Cycle de vie et inactivité donne les délais et comment les changer.
La supprimer
DeleteSandbox efface pour de bon la mémoire et le disque de la sandbox, et répond avec son registre final, ce qu’elle a consommé compris.
gone = sandboxes.delete_sandbox(sandbox.sandbox_id)
print(gone.state.name, gone.usage)
# DELETED Usage(running_seconds=11, paused_seconds=0, stored_gib_hours=0.0, cost_micros=0)
# cost_micros is what was charged so far: its last seconds are charged a moment later,
# and get_sandbox(sandbox.sandbox_id).usage then says cost_micros=110
const gone = await sandboxes.deleteSandbox({ sandboxId });
console.log(gone.state, gone.usage);
gone, err := client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: id})
if err != nil {
log.Fatal(err)
}
fmt.Println(gone.State, *gone.Usage)
let gone = sandboxes
.delete_sandbox(DeleteSandboxRequest { sandbox_id: id, ..Default::default() })
.await?;
println!("{:?} {:?}", gone.state, gone.usage);
DeleteSandbox {"sandbox_id": "…"}
La même chose avec la CLI pethost
pethost sandbox, ou pethost sbx, fait chacune de ces étapes depuis un terminal, via le SDK Go. Le nom d’une sandbox marche partout où marche son ID.
Step 1: Connectez-vous
$ pethost login
La connexion se fait dans votre navigateur. Dans un script, définissez plutôt PETHOST_TOKEN.
Step 2: Créez une sandbox
$ pethost sandbox new --name api-dev
✓ Made sandbox api-dev (exdei47yr5je70v5): default, running, from base@17, in <1 s
exdei47yr5je70v5
Next: pethost sandbox run exdei47yr5je70v5 -- <command> · pethost sandbox shell exdei47yr5je70v5
L’ID est affiché seul sur stdout : id=$(pethost sandbox new) le garde donc.
Step 3: Lancez une commande, et copiez-y des fichiers
$ pethost sandbox run api-dev -- python3 -c 'print(6 * 7)'
42
$ pethost sandbox cp ./app api-dev:app
✓ Copied ./app to exdei47yr5je70v5:app · 2 KB in <1 s
Step 4: Ouvrez un port
$ pethost sandbox run api-dev -d --wait-for-port 8000 -- python3 -m http.server 8000
It runs on in the sandbox. Its output so far: pethost api GetCommand '{"sandbox_id": "exdei47yr5je70v5", "command_id": "5f2mo5wikluq"}'
5f2mo5wikluq
$ pethost sandbox ports api-dev --open 8000
8000 https://8000-exdei47yr5je70v5.sbx1.sandboxes.pethost.network
Step 5: Mettez-la en pause, puis supprimez-la
$ pethost sandbox pause api-dev
exdei47yr5je70v5 paused
$ pethost sandbox rm api-dev --yes
exdei47yr5je70v5 deleted
Avec plusieurs espaces de travail de sandboxes, nommez-en un avec -w. La référence de la CLI donne chaque commande.
La même chose depuis votre agent
Un agent qui parle MCP reçoit les sandboxes comme outils : ajoutez https://mcp.pethost.dev/sandboxes à Claude Code, Codex, Cursor ou Claude, connectez-vous dans votre navigateur, et demandez-lui de lancer quelque chose dans une sandbox. Connecter un agent donne les étapes pour chacun.
Ce que le client fait pour vous
Deux services répondent. La console, à console.pethost.dev, tient le registre de chaque sandbox : création, paramètres, pause, duplication, suppression. Le serveur de la sandbox exécute ce qui se passe à l’intérieur : commandes, fichiers, bureau, liens et agents de code. Un appel du second type a besoin de l’adresse de ce serveur et d’un token pour cette seule sandbox. Le client prend les deux dans la réponse de CreateSandbox ou de ForkSandbox, ou les demande à ConnectSandbox, les garde jusqu’à peu avant leur expiration, et redemande une fois quand un serveur les refuse. Votre token d’API ne va jamais au serveur d’une sandbox.
Un appel qui crée quelque chose prend un request_id. Le client TypeScript en donne un à chaque appel quand vous l’omettez, et le garde quand il répète l’appel à une nouvelle connexion : le serveur ne le fait donc qu’une fois. Envoyez le vôtre et renvoyez-le quand vous réessayez après une réponse perdue : le nouvel essai répond ce qu’a fait le premier appel, pendant 24 heures.
Dans quel espace de travail agit un appel
Un appel qui nomme une sandbox agit dans l’espace de travail de cette sandbox. Tout autre appel agit dans l’espace de travail que nomme sa requête (workspace, par ID ou par nom), sinon dans celui avec lequel le client a été créé, sinon dans votre seul espace de travail de sandboxes. Un token qui en atteint plusieurs avec un appel qui n’en nomme aucun est refusé avec WorkspaceChoice, qui les liste.
Quand ça ne marche pas
FAILED_PRECONDITIONavecWorkspaceChoice: le token atteint plusieurs espaces de travail de sandboxes. Nommez-en un :Sandboxes(workspace="..."),workspacedans la requête, ou-wpour la CLI.PERMISSION_DENIEDsurCreateSandbox: le token n’a pas reçu cet espace de travail. Créez-en un depuis Connecter un agent ou votre code de cet espace de travail, ou accordez-le dans les Paramètres.UNAUTHENTICATED: le token manque, est mal saisi ou révoqué. VérifiezPETHOST_TOKENdans le shell qui lance le programme.RESOURCE_EXHAUSTEDavecLimitReached,vcpus: les sandboxes de l’espace de travail occupent tous ses vCPU, actives comme en pause. L’essai gratuit en a 4 : une sandbox DEFAULT, ou deux SMALL. Supprimez-en ou arrêtez-en une, ou demandezSMALL.RESOURCE_EXHAUSTEDavecLimitReached,starts_per_minute,_hourou_day: trop de démarrages dans cette fenêtre. Les démarrages sont gratuits, et limités :retry_timedit quand l’appel passera. Limites donne celles de chaque offre.- La commande répond RUNNING : elle a duré plus de 45 s et continue.
GetCommandavec soncommand_idattend de nouveau.
Erreurs liste chaque refus et ce qu’il faut faire.
Questions
Faut-il un SDK à part pour les sandboxes ?
Non. Le client des sandboxes fait partie du SDK de Pethost en Python, TypeScript, Go et Rust : installez pethost et importez son module sandboxes.
Où obtenir un token d’API ?
Dans la console, dans votre espace de travail de sandboxes : Connecter un agent ou votre code, puis Créer un token d’API. Il commence par pth_ et n’est affiché qu’une fois.
Y a-t-il un essai gratuit ?
Oui : 7 jours avec 1 $ de consommation et 4 vCPU, pour le premier espace de travail de sandboxes d’un nouveau compte. Une carte est demandée.
Que se passe-t-il si j’oublie une sandbox ?
Elle se met en pause après 5 minutes d’inactivité et s’arrête après 30 : elle ne coûte alors que ses données stockées. Elle n’est jamais supprimée, sauf si vous la supprimez ou fixez delete_after_idle_seconds.
Puis-je appeler l’API sans SDK ?
Oui. Les deux services parlent Connect, gRPC et gRPC-Web : un POST de JSON vers /pethost.sandboxes.v1.SandboxService/<Method> avec votre token marche, et la référence de l’API donne chaque champ.
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.