Dokumentacja Agent Sandboxes · Zadania
Uruchamianie poleceń i edycja plików w sandboxie
Uruchom polecenie w sandboxie i dostań jego wyjście i kod wyjścia jednym wywołaniem, śledź długie na bieżąco, edytuj pliki przez dokładną zamianę, przenoś pliki dowolnej wielkości przez linki i otwórz terminal w przeglądarce.
RunCommanduruchamiabash -lcjakouserw/home/useri czeka do 45 s: zwraca kod wyjścia i ostatnie 32 KiB wyjścia albo RUNNING z id polecenia.WatchCommandprzesyła wyjście polecenia na bieżąco;GetCommandczeka ponownie i czyta tylko to, co nowe.WriteFileszapisuje, edytuje, przenosi i usuwa pliki jednym wywołaniem, po kolei; edycja zamienia tekst, który występuje dokładnie raz.- Linki przenoszą pliki dowolnej wielkości i otwierają terminal w przeglądarce.
Przykłady są ciągiem dalszym szybkiego startu: sandboxes (client w Go) to klient, a id sandboxa jest pod ręką.
Step 1: Uruchom polecenie
Polecenie to jeden ciąg znaków, uruchamiany przez bash -lc, więc działają potoki, && i zmienne. cwd i user zmieniają, gdzie i jako kto działa; user to root albo domyślny user, który ma sudo bez hasła.
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: Śledź długie polecenie
Z wait_seconds 0 wywołanie odpowiada, gdy tylko polecenie wystartuje. WatchCommand wysyła potem jego wyjście od ostatnich 64 KiB, na bieżąco, a na końcu polecenie takie, jakim się zakończyło.
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
Bez strumienia GetCommand czeka ponownie do 45 s. Przekaż stdout_bytes z ostatnio odczytanej odpowiedzi jako stdout_after_bytes, a wyśle tylko to, co przyszło później.
Step 3: Zapisuj, edytuj i czytaj pliki
WriteFiles przyjmuje listę zmian i wprowadza je po kolei: text albo data zapisuje cały plik (z mode, a bez niego 0644), edit zamienia jeden dokładny fragment pliku, move_to go przenosi, delete usuwa plik albo katalog, make_directory tworzy katalog. Brakujące katalogi powstają same, a paczka zatrzymuje się na pierwszej zmianie, która się nie uda.
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: Przenieś duży plik przez link
Wywołanie niesie 1 MiB, WriteFiles 17 MiB, a ReadFile 1 MiB. Plik dowolnej wielkości przechodzi zamiast tego przez link: CreateLink z download_path daje URL do GET, a katalog przychodzi jako .tar; z upload_path URL, pod który robisz PUT z bajtami pliku. Każdy działa raz i idzie prosto do serwera sandboxa.
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: Otwórz terminal w przeglądarce
CreateLink z terminal daje stronę z powłoką w sandboxie, w której człowiek może pisać; jego command uruchamia program zamiast powłoki, jak claude. WebSocket pod tym samym URL-em przenosi bajty terminala w obie strony, dla twojego własnego terminala.
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:~$
Link wygasa po godzinie, chyba że ttl_seconds mówi inaczej, najwyżej po 86 400 s, i trzyma token w swoim URL-u: daj go osobie, która go użyje, nigdy stronie, którą czytają inni. Utworzenie linku niczego nie budzi.
Gdzie działa polecenie
Polecenie działa w maszynie wirtualnej sandboxa jako user (uid 1000, sudo bez hasła, w grupie docker) w /home/user albo jako root. Jego środowisko to środowisko szablonu, a nad nim własne zmienne sandboxa (settings.environment). stdin daje mu wejście, które potem się zamyka. Polecenie działa, dopóki się nie skończy, do timeout_seconds albo do StopCommand: kończy się czekanie wywołania, nie polecenie.
Wywołanie do wstrzymanego sandboxa najpierw go budzi, w ok. 80 ms. Proces zostawiony w tle (serwer uruchomiony z &) przeżywa wstrzymania, ale sam nie pozwala sandboxowi zasnąć: długie zadanie uruchom z keep_awake, żeby licznik wstrzymania na nie czekał (keep_awake).
Wyjście, offsety i historia
Odpowiedź zawiera ostatnie 32 KiB stdout i stderr, w UTF-8, z output_truncated, gdy początek został ucięty, oraz stdout_bytes i stderr_bytes, czyli wszystko, co zostało zapisane. exit_code to kod powłoki: 128 plus numer sygnału, gdy zakończył je sygnał, i brak, dopóki działa. Sandbox trzyma ostatnie 100 zakończonych poleceń dla GetCommand. ListCommands wymienia te, które teraz działają, uruchomione przez API, przez SSH albo w terminalu.
StopCommand wysyła SIGTERM, a 10 s później SIGKILL, jeśli polecenie wciąż działa. Wywołane dla polecenia, które się zakończyło, zabija to, co zostawiło działające w tle.
Edycja przez dokładną zamianę
edit zamienia old_text na new_text, gdy old_text występuje w pliku dokładnie raz, a plik ma najwyżej 16 MiB. Brak wystąpienia to EDIT_NOT_FOUND; dwa lub więcej to EDIT_AMBIGUOUS, a plik w obu przypadkach zostaje bez zmian. To edycja, jaką robią agenci kodujący, i głośno się nie udaje tam, gdzie numer linii byłby już nieaktualny. Zapis zastępuje cały plik i zachowuje jego właściciela i uprawnienia; przez dowiązanie symboliczne zapisuje do jego celu.
WatchFiles przesyła to, co powstaje, jest zapisywane, usuwane i przemianowywane w katalogu, a z recursive także w jego podkatalogach. OVERFLOW oznacza, że zdarzenia przepadły: wylistuj katalog ponownie.
Docker w sandboxie
Każdy sandbox z base ma Dockera, z Compose i Buildx. Jego demon startuje przy pierwszym połączeniu z /var/run/docker.sock i do tego czasu nic nie kosztuje. Obrazy i kontenery są na dysku sandboxa, więc zatrzymanie je zachowuje, a szablon je przenosi. Pobrania z Docker Hub idą najpierw przez mirror.
Gdy to nie działa
- Odpowiedź to RUNNING, bez kodu wyjścia: polecenie trwało dłużej niż
wait_secondsi działa dalej. Śledź je przezWatchCommandalbo czekaj przezGetCommand. - Sandbox wstrzymał się w trakcie długiego buildu: nic go nie wywoływało, gdy build trwał. Taką pracę uruchamiaj z
keep_awakeitimeout_seconds. failuretoEDIT_NOT_FOUNDalboEDIT_AMBIGUOUS: odczytaj plik ponownie i wyślijold_text, który występuje raz; zmiany przed nim w paczce zostały wprowadzone (done_count).RESOURCE_EXHAUSTEDbezLimitReached: żądanie przekroczyło swój limit (plik ponad 17 MiB: użyj linku do wgrania) albo sandbox obsługuje już 64 wywołań naraz. Zakończ któreś albo poczekaj.FAILED_PRECONDITIONzeStopped: sandbox jest zatrzymany.ResumeSandboxgo uruchamia, z plikami takimi, jakie zostawił.- Polecenie, które było RUNNING, jest
LOST: sandbox stracił pamięć (zatrzymał się), gdy polecenie działało. Uruchom je ponownie.
Pytania
Jak długo może działać polecenie?
Tyle, ile potrzebuje: wywołanie czeka do 45 s, a polecenie działa dalej. Wcześniej kończy je tylko timeout_seconds albo StopCommand.
Czy mogę uruchamiać polecenia jako root?
Tak: user root albo sudo, które user ma bez hasła.
Jak wgrać duży plik do sandboxa?
CreateLink z upload_path daje URL, pod który robisz PUT z plikiem dowolnej wielkości, albo zrobi to za ciebie pethost sandbox cp.
Czy mogę uruchamiać Dockera w sandboxie?
Tak. Docker, Compose i Buildx są w base, a demon startuje przy pierwszym użyciu.
Czy działający proces w tle nie pozwala sandboxowi zasnąć?
Nie. Przeżywa wstrzymania, a żądanie do jego portu budzi sandbox, ale przed wstrzymaniem chronią go tylko wywołania, sesje i polecenia z keep_awake.
Wypróbuj Pethost Agent Sandboxes
Okres próbny na 7 dni z 1 $ zużycia i 4 vCPU, z kartą. Potem plan od 20 $ miesięcznie, który zawiera tyle samo zużycia.