Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Aufgaben

Befehle ausführen und Dateien bearbeiten in einer Sandbox

Aktualisiert · 9 Min. Lesezeit

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.

Kurz gesagt
  • RunCommand führt bash -lc als user in /home/user aus und wartet bis zu 45 s: sein Exit-Code und die letzten 32 KiB seiner Ausgabe, oder RUNNING mit seiner ID.
  • WatchCommand streamt die Ausgabe eines Befehls, wie sie kommt; GetCommand wartet erneut und liest nur das Neue.
  • WriteFiles schreibt, 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.

Python
command = sandboxes.run_command(sandbox_id, command="uname -r && whoami", cwd="/tmp")
print(command.exit_code)
print(command.stdout)
# 0
# 6.18.63
# user
TypeScript
const command = await sandboxes.runCommand({ sandboxId, command: "uname -r && whoami", cwd: "/tmp" });
console.log(command.exitCode);
console.log(command.stdout);
Go
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)
Rust
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);
CLI
$ 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.

Python
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
TypeScript
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);
}
Go
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)
	}
}
Rust
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),
        _ => {}
    }
}
CLI
$ 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.

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

Python
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…
TypeScript
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);
Go
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)
Rust
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);
CLI
$ 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.

Python
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…
TypeScript
const terminal = await sandboxes.createLink({ sandboxId, terminal: {}, ttlSeconds: 900 });
console.log(terminal.url);
Go
terminal, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{
	SandboxID:  id,
	Target:     sandboxes.CreateLinkTerminal{},
	TTLSeconds: 900,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(terminal.URL)
Rust
let terminal = sandboxes
    .create_link(CreateLinkRequest {
        sandbox_id: id.clone(),
        target: Some(CreateLinkRequestTarget::Terminal(TerminalLink::default())),
        ttl_seconds: 900,
    })
    .await?;
println!("{}", terminal.url);
CLI
$ 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_seconds gedauert und läuft weiter. Folge ihm mit WatchCommand oder warte mit GetCommand.
  • Die Sandbox hat mitten in einem langen Build pausiert: Nichts hat sie aufgerufen, während der Build lief. Starte solche Arbeit mit keep_awake und einem timeout_seconds.
  • failure ist EDIT_NOT_FOUND oder EDIT_AMBIGUOUS: Lies die Datei neu und schick ein old_text, das einmal vorkommt; die Änderungen davor im Stapel wurden gemacht (done_count).
  • RESOURCE_EXHAUSTED ohne LimitReached: 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_PRECONDITION mit Stopped: Die Sandbox ist gestoppt. ResumeSandbox startet 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.

Testphase starten