Doku zu Agent Sandboxes · Aufgaben
Befehle ausführen und Dateien bearbeiten in einer Sandbox
Führ einen Befehl in einer Sandbox aus und bekomm seine Ausgabe und seinen Exit-Code in einem Aufruf, folge einem langen, während er läuft, bearbeite Dateien durch exaktes Ersetzen, bewege Dateien jeder Größe über Links und öffne ein Terminal im Browser.
RunCommandführtbash -lcalsuserin/home/useraus und wartet bis zu 45 s: sein Exit-Code und die letzten 32 KiB seiner Ausgabe, oder RUNNING mit seiner ID.WatchCommandstreamt die Ausgabe eines Befehls, wie sie kommt;GetCommandwartet erneut und liest nur das Neue.WriteFilesschreibt, bearbeitet, verschiebt und löscht Dateien in einem Aufruf, der Reihe nach; eine Bearbeitung ersetzt Text, der genau einmal vorkommt.- Links bewegen Dateien jeder Größe und öffnen ein Terminal im Browser.
Die Beispiele schließen an den Schnellstart an: sandboxes (client in Go) ist ein Client, und die ID der Sandbox liegt bereit.
Step 1: Befehl ausführen
Ein Befehl ist ein String, ausgeführt von bash -lc, also funktionieren Pipes, && und Variablen. cwd und user ändern, wo und als wer er läuft; user ist root oder der Standard, user, der sudo ohne Passwort hat.
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: Einem langen Befehl folgen
Mit wait_seconds 0 antwortet der Aufruf, sobald der Befehl gestartet ist. WatchCommand schickt dann seine Ausgabe ab den letzten 64 KiB, wie sie kommt, und den Befehl, wie er zuletzt endete.
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
Ohne Stream wartet GetCommand erneut bis zu 45 s. Gib die stdout_bytes der zuletzt gelesenen Antwort als stdout_after_bytes mit, und es schickt nur, was danach kam.
Step 3: Dateien schreiben, bearbeiten und lesen
WriteFiles nimmt eine Liste von Änderungen und macht sie der Reihe nach: text oder data schreibt eine ganze Datei (mit mode, sonst 0644), edit ersetzt ein exaktes Stück einer Datei, move_to verschiebt sie, delete löscht eine Datei oder ein Verzeichnis, make_directory legt eins an. Fehlende Verzeichnisse werden angelegt, und der Stapel hält bei der ersten Änderung an, die scheitert.
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: Große Datei über einen Link bewegen
Ein Aufruf trägt 1 MiB, WriteFiles 17 MiB und ReadFile 1 MiB. Eine Datei jeder Größe geht stattdessen über einen Link: CreateLink mit download_path gibt eine URL für ein GET, ein Verzeichnis kommt als .tar; mit upload_path eine URL, an die du die Bytes der Datei per PUT schickst. Jeder funktioniert einmal und geht direkt an den Server der 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: Terminal im Browser öffnen
CreateLink mit terminal gibt eine Seite mit einer Shell in der Sandbox, in die eine Person tippen kann; sein command führt statt der Shell ein Programm aus, etwa claude. Ein WebSocket an dieselbe URL trägt die Bytes des Terminals in beide Richtungen, für ein eigenes Terminal.
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:~$
Ein Link läuft nach einer Stunde ab, außer ttl_seconds sagt etwas anderes, höchstens 86.400 s, und trägt ein Token in seiner URL: Gib ihn der Person, die ihn nutzt, nie einer Seite, die andere lesen. Ihn zu erstellen weckt nichts.
Wo ein Befehl läuft
Ein Befehl läuft in der VM der Sandbox als user (uid 1000, sudo ohne Passwort, in der Gruppe docker) in /home/user, oder als root. Seine Umgebung ist die der Vorlage, darüber die eigenen Variablen der Sandbox (settings.environment). stdin gibt ihm eine Eingabe, die danach geschlossen wird. Ein Befehl läuft, bis er endet, bis timeout_seconds oder bis StopCommand: Das Warten des Aufrufs endet, der Befehl nicht.
Ein Aufruf in eine pausierte Sandbox weckt sie zuerst, in etwa 80 ms. Ein Hintergrundprozess, der weiterläuft (ein Server, mit & gestartet), übersteht Pausen, hält die Sandbox aber nicht von selbst wach: Starte einen langen Job mit keep_awake, damit der Pause-Timer auf ihn wartet (keep_awake).
Ausgabe, Offsets und Verlauf
Eine Antwort hält die letzten 32 KiB von stdout und von stderr, als UTF-8, mit output_truncated, wenn der Anfang abgeschnitten wurde, und stdout_bytes und stderr_bytes, alles, was geschrieben wurde. exit_code ist der der Shell: 128 plus die Nummer des Signals, wenn ein Signal ihn beendet hat, und fehlt, solange er läuft. Die Sandbox behält ihre letzten 100 beendeten Befehle für GetCommand. ListCommands listet die, die gerade laufen, gestartet über die API, über SSH oder in einem Terminal.
StopCommand schickt SIGTERM und 10 s später SIGKILL, wenn der Befehl noch läuft. Für einen beendeten Befehl aufgerufen, beendet es, was dieser Befehl im Hintergrund laufen ließ.
Bearbeiten durch exaktes Ersetzen
Ein edit ersetzt old_text durch new_text, wo old_text genau einmal in der Datei vorkommt, die höchstens 16 MiB groß ist. Nicht vorhanden ist EDIT_NOT_FOUND; zweimal oder öfter ist EDIT_AMBIGUOUS, und die Datei bleibt in beiden Fällen unverändert. Das ist die Bearbeitung, die Coding-Agenten machen, und sie scheitert laut, wo eine Zeilennummer veraltet gewesen wäre. Ein Schreiben ersetzt eine ganze Datei und behält ihren Besitzer und Modus; es schreibt durch einen symbolischen Link in sein Ziel.
WatchFiles streamt, was unter einem Verzeichnis erstellt, geschrieben, entfernt und umbenannt wird, mit recursive auch darunter. OVERFLOW sagt, dass Events verloren gingen: Liste das Verzeichnis neu.
Docker in einer Sandbox
Jede Sandbox aus base hat Docker, mit Compose und Buildx. Sein Daemon startet bei der ersten Verbindung zu /var/run/docker.sock und kostet bis dahin nichts. Images und Container liegen auf der Disk der Sandbox, also behält ein Stopp sie, und eine Vorlage nimmt sie mit. Pulls von Docker Hub gehen zuerst über einen Mirror.
Wenn es nicht funktioniert
- Die Antwort ist RUNNING, ohne Exit-Code: Der Befehl hat länger als
wait_secondsgedauert und läuft weiter. Folge ihm mitWatchCommandoder warte mitGetCommand. - Die Sandbox hat mitten in einem langen Build pausiert: Nichts hat sie aufgerufen, während der Build lief. Starte solche Arbeit mit
keep_awakeund einemtimeout_seconds. failureistEDIT_NOT_FOUNDoderEDIT_AMBIGUOUS: Lies die Datei neu und schick einold_text, das einmal vorkommt; die Änderungen davor im Stapel wurden gemacht (done_count).RESOURCE_EXHAUSTEDohneLimitReached: Der Request lag über seiner Grenze (eine Datei über 17 MiB: Nimm einen Upload-Link), oder die Sandbox bedient schon 64 Aufrufe gleichzeitig. Beende einen, oder warte.FAILED_PRECONDITIONmitStopped: Die Sandbox ist gestoppt.ResumeSandboxstartet sie, ihre Dateien, wie sie sie verlassen hat.- Ein Befehl, der RUNNING war, ist
LOST: Die Sandbox hat ihren RAM verloren (sie wurde gestoppt), während der Befehl lief. Führ ihn noch einmal aus.
Fragen
Wie lange kann ein Befehl laufen?
So lange er braucht: Der Aufruf wartet bis zu 45 s, und der Befehl läuft weiter. Nur timeout_seconds oder StopCommand beenden ihn früher.
Kann ich Befehle als root ausführen?
Ja: user root, oder sudo, das user ohne Passwort hat.
Wie lade ich eine große Datei in eine Sandbox hoch?
CreateLink mit upload_path gibt eine URL, an die du die Datei per PUT schickst, in jeder Größe, oder pethost sandbox cp erledigt das für dich.
Kann ich Docker in einer Sandbox ausführen?
Ja. Docker, Compose und Buildx sind in base, und der Daemon startet bei der ersten Nutzung.
Hält ein laufender Hintergrundprozess die Sandbox wach?
Nein. Er übersteht Pausen, und ein Request an seinen Port weckt die Sandbox, aber nur Aufrufe, Sitzungen und keep_awake-Befehle verhindern, dass sie pausiert.
Pethost Agent Sandboxes ausprobieren
Eine Testphase von 7 Tagen mit 1 $ Verbrauch und 4 vCPUs, mit Karte. Danach ein Tarif ab 20 $ im Monat, der genauso viel Verbrauch enthält.