Français
Menu de la documentation

Documentation Agent Sandboxes · Premiers pas

Démarrage rapide : votre première sandbox

Mis à jour le · 12 min de lecture

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.

En bref
  • 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.

Python
pip install pethost
TypeScript
npm install pethost          # or: bun add pethost
deno add jsr:@pethost/sdk    # Deno: import from "@pethost/sdk/sandboxes"
Go
go get github.com/pethost-dev/sdk/go
Rust
cargo add pethost
cargo add tokio --features macros,rt-multi-thread,time
CLI
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.

Python
from pethost.sandboxes import Sandboxes

sandboxes = Sandboxes()  # reads PETHOST_TOKEN
sandbox = sandboxes.create_sandbox("base")
print(sandbox.sandbox_id, sandbox.state.name)  # 5a4c9z5zw58mvqww RUNNING
TypeScript
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);
Go
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.
}
Rust
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(())
}
HTTP
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.

Python
command = sandboxes.run_command(sandbox.sandbox_id, command="python3 -c 'print(6 * 7)'")
print(command.exit_code, command.stdout)  # 0 42
TypeScript
const command = await sandboxes.runCommand({ sandboxId, command: "python3 -c 'print(6 * 7)'" });
console.log(command.exitCode, command.stdout); // 0 42
Go
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
Rust
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
HTTP
# 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.

Python
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')
TypeScript
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);
Go
_, 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))
}
Rust
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.

Python
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
TypeScript
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);
Go
_, 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)
Rust
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);
}
MCP
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 :

Python
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
TypeScript
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
Go
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
Rust
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
MCP
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.

Python
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
TypeScript
const gone = await sandboxes.deleteSandbox({ sandboxId });
console.log(gone.state, gone.usage);
Go
gone, err := client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: id})
if err != nil {
	log.Fatal(err)
}
fmt.Println(gone.State, *gone.Usage)
Rust
let gone = sandboxes
    .delete_sandbox(DeleteSandboxRequest { sandbox_id: id, ..Default::default() })
    .await?;
println!("{:?} {:?}", gone.state, gone.usage);
MCP
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_PRECONDITION avec WorkspaceChoice : le token atteint plusieurs espaces de travail de sandboxes. Nommez-en un : Sandboxes(workspace="..."), workspace dans la requête, ou -w pour la CLI.
  • PERMISSION_DENIED sur CreateSandbox : 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érifiez PETHOST_TOKEN dans le shell qui lance le programme.
  • RESOURCE_EXHAUSTED avec LimitReached, 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 demandez SMALL.
  • RESOURCE_EXHAUSTED avec LimitReached, starts_per_minute, _hour ou _day : trop de démarrages dans cette fenêtre. Les démarrages sont gratuits, et limités : retry_time dit quand l’appel passera. Limites donne celles de chaque offre.
  • La commande répond RUNNING : elle a duré plus de 45 s et continue. GetCommand avec son command_id attend 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.

Démarrer l’essai gratuit