Documentation Agent Sandboxes · Tâches
Lancer des commandes et modifier des fichiers dans une sandbox
Lancez une commande dans une sandbox et obtenez sa sortie et son code de sortie en un appel, suivez une longue commande pendant qu’elle tourne, modifiez des fichiers par remplacement exact, déplacez des fichiers de toute taille par des liens, et ouvrez un terminal dans un navigateur.
RunCommandlancebash -lcen tant queuserdans/home/useret attend jusqu’à 45 s : son code de sortie et les derniers 32 KiB de sa sortie, ou RUNNING avec son ID.WatchCommanddiffuse la sortie d’une commande au fil de l’eau ;GetCommandattend de nouveau et ne lit que ce qui est nouveau.WriteFilesécrit, modifie, déplace et supprime des fichiers en un appel, dans l’ordre ; une modification remplace un texte présent exactement une fois.- Des liens déplacent des fichiers de toute taille et ouvrent un terminal dans un navigateur.
Les exemples reprennent le démarrage rapide : sandboxes (client en Go) est un client, et l’ID de la sandbox est sous la main.
Step 1: Lancez une commande
Une commande est une seule chaîne, exécutée par bash -lc : les pipes, && et les variables marchent donc. cwd et user changent où et sous quelle identité elle s’exécute ; user vaut root ou la valeur par défaut, user, qui a sudo sans mot de passe.
command = sandboxes.run_command(sandbox_id, command="uname -r && whoami", cwd="/tmp")
print(command.exit_code)
print(command.stdout)
# 0
# 6.18.63
# user
const command = await sandboxes.runCommand({ sandboxId, command: "uname -r && whoami", cwd: "/tmp" });
console.log(command.exitCode);
console.log(command.stdout);
command, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: "uname -r && whoami", Cwd: "/tmp"})
if err != nil {
log.Fatal(err)
}
fmt.Println(*command.ExitCode)
fmt.Println(command.Stdout)
let command = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "uname -r && whoami".into(),
cwd: "/tmp".into(),
..Default::default()
})
.await?;
println!("{:?}", command.exit_code);
println!("{}", command.stdout);
$ pethost sandbox run api-dev --cwd /tmp -- 'uname -r && whoami'
6.18.63
user
Step 2: Suivez une longue commande
Avec wait_seconds à 0, l’appel répond dès que la commande a démarré. WatchCommand envoie ensuite sa sortie à partir des derniers 64 KiB, au fil de l’eau, puis la commande telle qu’elle s’est terminée.
import sys
job = sandboxes.run_command(
sandbox_id,
command="for i in 1 2 3; do echo step $i; sleep 20; done",
wait_seconds=0,
timeout_seconds=600,
)
for out in sandboxes.watch_command(sandbox_id, command_id=job.command_id):
if out.stdout is not None:
sys.stdout.write(out.stdout.decode())
if out.ended is not None:
print("exit", out.ended.exit_code)
# step 1
# step 2
# step 3
# exit 0
const job = await sandboxes.runCommand({
sandboxId,
command: "for i in 1 2 3; do echo step $i; sleep 20; done",
waitSeconds: 0,
timeoutSeconds: 600,
});
for await (const out of sandboxes.watchCommand({ sandboxId, commandId: job.commandId })) {
if (out.output === "stdout") process.stdout.write(out.stdout);
if (out.output === "ended") console.log("exit", out.ended.exitCode);
}
job, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
SandboxID: id,
Command: "for i in 1 2 3; do echo step $i; sleep 20; done",
WaitSeconds: new(uint32(0)),
TimeoutSeconds: 600,
})
if err != nil {
log.Fatal(err)
}
for out, err := range client.WatchCommand(ctx, &sandboxes.WatchCommandRequest{SandboxID: id, CommandID: job.CommandID}) {
if err != nil {
log.Fatal(err)
}
switch output := out.Output.(type) {
case sandboxes.CommandOutputStdout:
os.Stdout.Write(output)
case sandboxes.CommandOutputEnded:
fmt.Println("exit", *output.ExitCode)
}
}
let job = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "for i in 1 2 3; do echo step $i; sleep 20; done".into(),
wait_seconds: Some(0),
timeout_seconds: 600,
..Default::default()
})
.await?;
let mut output = sandboxes.watch_command(WatchCommandRequest {
sandbox_id: id.clone(),
command_id: job.command_id,
});
while let Some(out) = output.next().await {
match out?.output {
Some(CommandOutputOutput::Stdout(bytes)) => print!("{}", String::from_utf8_lossy(&bytes)),
Some(CommandOutputOutput::Ended(ended)) => println!("exit {:?}", ended.exit_code),
_ => {}
}
}
$ pethost sandbox run api-dev --timeout 10m -- 'for i in 1 2 3; do echo step $i; sleep 20; done'
step 1
step 2
step 3
Sans flux, GetCommand attend de nouveau jusqu’à 45 s. Passez le stdout_bytes de la dernière réponse lue comme stdout_after_bytes, et il n’envoie que ce qui est venu après.
Step 3: Écrivez, modifiez et lisez des fichiers
WriteFiles prend une liste de changements et les applique dans l’ordre : text ou data écrit un fichier entier (avec mode, sinon 0644), edit remplace un morceau exact d’un fichier, move_to le déplace, delete supprime un fichier ou un dossier, make_directory en crée un. Les dossiers manquants sont créés, et le lot s’arrête au premier changement qui échoue.
from pethost.sandboxes import FileChange, TextEdit
done = sandboxes.write_files(sandbox_id, changes=[
FileChange(path="app/run.sh", text="#!/bin/sh\necho ready\n", mode="0755"),
FileChange(path="app/run.sh", edit=TextEdit(old_text="ready", new_text="ready to go")),
])
print(done.done_count, done.failure.name)
for entry in sandboxes.list_files(sandbox_id, path="app").files:
print(entry.path, entry.mode, entry.size_bytes)
print(sandboxes.read_file(sandbox_id, path="app/run.sh").text)
# 2 UNSPECIFIED
# /home/user/app/run.sh 0755 27
# #!/bin/sh
# echo ready to go
const done = await sandboxes.writeFiles({
sandboxId,
changes: [
{ path: "app/run.sh", text: "#!/bin/sh\necho ready\n", mode: "0755" },
{ path: "app/run.sh", edit: { oldText: "ready", newText: "ready to go" } },
],
});
console.log(done.doneCount, done.failure);
const { files } = await sandboxes.listFiles({ sandboxId, path: "app" });
for (const entry of files) console.log(entry.path, entry.mode, entry.sizeBytes);
console.log((await sandboxes.readFile({ sandboxId, path: "app/run.sh" })).text);
done, err := client.WriteFiles(ctx, &sandboxes.WriteFilesRequest{SandboxID: id, Changes: []sandboxes.FileChange{
{Path: "app/run.sh", Change: sandboxes.FileChangeText("#!/bin/sh\necho ready\n"), Mode: "0755"},
{Path: "app/run.sh", Change: sandboxes.FileChangeEdit{OldText: "ready", NewText: "ready to go"}},
}})
if err != nil {
log.Fatal(err)
}
fmt.Println(done.DoneCount, done.Failure)
list, err := client.ListFiles(ctx, &sandboxes.ListFilesRequest{SandboxID: id, Path: "app"})
if err != nil {
log.Fatal(err)
}
for _, entry := range list.Files {
fmt.Println(entry.Path, entry.Mode, entry.SizeBytes)
}
let script = |change| FileChange { path: "app/run.sh".into(), change: Some(change), ..Default::default() };
let done = sandboxes
.write_files(WriteFilesRequest {
sandbox_id: id.clone(),
changes: vec![
FileChange { mode: "0755".into(), ..script(FileChangeChange::Text("#!/bin/sh\necho ready\n".into())) },
script(FileChangeChange::Edit(TextEdit { old_text: "ready".into(), new_text: "ready to go".into() })),
],
})
.await?;
println!("{} {:?}", done.done_count, done.failure);
let list = sandboxes
.list_files(ListFilesRequest { sandbox_id: id.clone(), path: "app".into(), ..Default::default() })
.await?;
for entry in list.files {
println!("{} {} {}", entry.path, entry.mode, entry.size_bytes);
}
Step 4: Déplacez un gros fichier par un lien
Un appel transporte 1 MiB, WriteFiles 17 MiB et ReadFile 1 MiB. Un fichier de toute taille passe plutôt par un lien : CreateLink avec download_path donne une URL à lire en GET, un dossier arrivant en .tar ; avec upload_path, une URL où envoyer les octets du fichier en PUT. Chacune marche une fois, et va directement au serveur de la sandbox.
upload = sandboxes.create_link(sandbox_id, upload_path="data/train.csv")
results = sandboxes.create_link(sandbox_id, download_path="results")
print(upload.url)
print(results.url)
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
const upload = await sandboxes.createLink({ sandboxId, uploadPath: "data/train.csv" });
const results = await sandboxes.createLink({ sandboxId, downloadPath: "results" });
console.log(upload.url);
console.log(results.url);
upload, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{SandboxID: id, Target: sandboxes.CreateLinkUploadPath("data/train.csv")})
if err != nil {
log.Fatal(err)
}
results, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{SandboxID: id, Target: sandboxes.CreateLinkDownloadPath("results")})
if err != nil {
log.Fatal(err)
}
fmt.Println(upload.URL)
fmt.Println(results.URL)
let link = |target| CreateLinkRequest { sandbox_id: id.clone(), target: Some(target), ..Default::default() };
let upload = sandboxes.create_link(link(CreateLinkRequestTarget::UploadPath("data/train.csv".into()))).await?;
let results = sandboxes.create_link(link(CreateLinkRequestTarget::DownloadPath("results".into()))).await?;
println!("{}", upload.url);
println!("{}", results.url);
$ pethost sandbox cp ./data/train.csv api-dev:data/train.csv
✓ Copied ./data/train.csv to zt01ocz93yiwpy31:data/train.csv · 22 KB in <1 s
$ pethost sandbox cp api-dev:results ./results
✓ Copied zt01ocz93yiwpy31:results to ./results · 4 KB in <1 s
curl -T train.csv "$UPLOAD_URL"
curl -o results.tar "$RESULTS_URL"
Step 5: Ouvrez un terminal dans un navigateur
CreateLink avec terminal donne une page avec un shell dans la sandbox, où une personne peut taper ; son command lance un programme à la place du shell, comme claude. Une WebSocket vers la même URL transporte les octets du terminal dans les deux sens, pour un terminal à vous.
from pethost.sandboxes import TerminalLink
print(sandboxes.create_link(sandbox_id, terminal=TerminalLink(), ttl_seconds=900).url)
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
const terminal = await sandboxes.createLink({ sandboxId, terminal: {}, ttlSeconds: 900 });
console.log(terminal.url);
terminal, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{
SandboxID: id,
Target: sandboxes.CreateLinkTerminal{},
TTLSeconds: 900,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(terminal.URL)
let terminal = sandboxes
.create_link(CreateLinkRequest {
sandbox_id: id.clone(),
target: Some(CreateLinkRequestTarget::Terminal(TerminalLink::default())),
ttl_seconds: 900,
})
.await?;
println!("{}", terminal.url);
$ pethost sandbox open api-dev --terminal
✓ Opened the terminal of e9bprbw1hovj6sw5 in your browser.
$ pethost sandbox shell api-dev
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.
user@e9bprbw1hovj6sw5:~$
Un lien expire au bout d’une heure, sauf si ttl_seconds dit autre chose, 86 400 s au plus, et porte un token dans son URL : donnez-le à la personne qui s’en servira, jamais à une page que d’autres lisent. En créer un ne réveille rien.
Où s’exécute une commande
Une commande s’exécute dans la VM de la sandbox en tant que user (uid 1000, sudo sans mot de passe, dans le groupe docker) dans /home/user, ou en tant que root. Son environnement est celui du template, avec par-dessus les variables propres à la sandbox (settings.environment). stdin lui donne une entrée, qui se ferme ensuite. Une commande tourne jusqu’à ce qu’elle se termine, jusqu’à timeout_seconds, ou jusqu’à StopCommand : c’est l’attente de l’appel qui prend fin, pas la commande.
Un appel vers une sandbox en pause la réveille d’abord, en 80 ms environ. Un processus laissé en arrière-plan (un serveur lancé avec &) survit aux pauses, mais ne garde pas à lui seul la sandbox éveillée : lancez une longue tâche avec keep_awake, pour que le délai de pause l’attende (keep_awake).
Sortie, positions et historique
Une réponse contient les derniers 32 KiB de stdout et de stderr, en UTF-8, avec output_truncated quand le début a été coupé, et stdout_bytes et stderr_bytes, tout ce qui a été écrit. exit_code est celui du shell : 128 plus le numéro du signal quand un signal l’a terminée, et absent tant qu’elle tourne. La sandbox garde ses 100 dernières commandes terminées pour GetCommand. ListCommands liste celles qui tournent maintenant, lancées par l’API, par SSH ou dans un terminal.
StopCommand envoie SIGTERM, puis SIGKILL 10 s plus tard si la commande tourne encore. Appelé pour une commande terminée, il tue ce qu’elle a laissé tourner en arrière-plan.
Modifications par remplacement exact
Une edit remplace old_text par new_text là où old_text apparaît exactement une fois dans le fichier, de 16 MiB au plus. Absent, c’est EDIT_NOT_FOUND ; présent deux fois ou plus, EDIT_AMBIGUOUS, et le fichier reste inchangé dans les deux cas. C’est la modification que font les agents de code, et elle échoue franchement là où un numéro de ligne aurait été périmé. Une écriture remplace un fichier entier et garde son propriétaire et son mode ; elle écrit à travers un lien symbolique, vers sa cible.
WatchFiles diffuse ce qui est créé, écrit, supprimé et renommé dans un dossier, avec recursive pour ce qui est en dessous. OVERFLOW dit que des événements ont été perdus : listez de nouveau le dossier.
Docker dans une sandbox
Chaque sandbox issue de base a Docker, avec Compose et Buildx. Son démon démarre à la première connexion à /var/run/docker.sock et ne coûte rien jusque-là. Les images et les conteneurs sont sur le disque de la sandbox : un arrêt les garde donc, et un template les emporte. Les téléchargements depuis Docker Hub passent d’abord par un miroir.
Quand ça ne marche pas
- La réponse est RUNNING, sans code de sortie : la commande a duré plus que
wait_secondset continue. Suivez-la avecWatchCommand, ou attendez avecGetCommand. - La sandbox s’est mise en pause pendant un long build : rien ne l’appelait pendant le build. Lancez ce genre de travail avec
keep_awakeet untimeout_seconds. failurevautEDIT_NOT_FOUNDouEDIT_AMBIGUOUS: relisez le fichier et envoyez unold_textprésent une seule fois ; les changements qui le précèdent dans le lot ont été faits (done_count).RESOURCE_EXHAUSTEDsansLimitReached: la requête dépassait sa limite (un fichier de plus de 17 MiB : utilisez un lien d’envoi), ou la sandbox sert déjà 64 appels en même temps. Terminez-en un, ou attendez.FAILED_PRECONDITIONavecStopped: la sandbox est arrêtée.ResumeSandboxla démarre, ses fichiers tels qu’elle les a laissés.- Une commande qui était RUNNING est
LOST: la sandbox a perdu sa mémoire (elle s’est arrêtée) pendant que la commande tournait. Relancez-la.
Questions
Combien de temps une commande peut-elle tourner ?
Aussi longtemps qu’il le faut : l’appel attend jusqu’à 45 s et la commande continue. Seuls timeout_seconds ou StopCommand la terminent plus tôt.
Puis-je lancer des commandes en root ?
Oui : user à root, ou sudo, que user a sans mot de passe.
Comment envoyer un gros fichier dans une sandbox ?
CreateLink avec upload_path donne une URL où envoyer le fichier en PUT, de toute taille, ou pethost sandbox cp le fait pour vous.
Puis-je faire tourner Docker dans une sandbox ?
Oui. Docker, Compose et Buildx sont dans base, et le démon démarre à la première utilisation.
Un processus en arrière-plan garde-t-il la sandbox éveillée ?
Non. Il survit aux pauses, et une requête vers son port réveille la sandbox, mais seuls les appels, les sessions et les commandes keep_awake l’empêchent de se mettre en pause.
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.