Русский
Меню документации

Документация Agent Sandboxes · Задачи

Команды и файлы в песочнице

Обновлено · 8 мин чтения

Выполните команду в песочнице и получите ее вывод и код выхода за один вызов, следите за долгой по ходу, правьте файлы точной заменой, передавайте файлы любого размера по ссылкам и открывайте терминал в браузере.

Коротко
  • RunCommand выполняет bash -lc от имени user в /home/user и ждет до 45 с: код выхода и последние 32 KiB вывода или RUNNING с ID команды.
  • WatchCommand присылает вывод команды потоком, по мере появления; GetCommand снова ждет и читает только новое.
  • WriteFiles записывает, правит, перемещает и удаляет файлы за один вызов, по порядку; правка заменяет текст, который встречается ровно один раз.
  • Ссылки передают файлы любого размера и открывают терминал в браузере.

Примеры продолжают быстрый старт: sandboxes (client в Go) — это клиент, а ID песочницы под рукой.

Step 1: Выполните команду

Команда — одна строка, которую выполняет bash -lc, поэтому работают пайпы, && и переменные. cwd и user меняют, где и от чьего имени она выполняется; user — это root или пользователь по умолчанию, user, у которого есть sudo без пароля.

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: Следите за долгой командой

С wait_seconds 0 вызов отвечает, как только команда запустилась. Затем WatchCommand присылает ее вывод начиная с последних 64 KiB, по мере появления, и команду такой, какой она завершилась.

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

Без потока GetCommand снова ждет до 45 с. Передайте stdout_bytes из последнего прочитанного ответа как stdout_after_bytes, и он пришлет только то, что появилось после.

Step 3: Запишите, поправьте и прочитайте файлы

WriteFiles принимает список изменений и делает их по порядку: text или data записывает файл целиком (с mode, иначе 0644), edit заменяет один точный фрагмент файла, move_to перемещает его, delete удаляет файл или папку, make_directory создает папку. Недостающие папки создаются, а пачка останавливается на первом неудавшемся изменении.

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: Передайте большой файл по ссылке

Вызов несет 1 MiB, WriteFiles — 17 MiB, а ReadFile — 1 MiB. Файл любого размера вместо этого передается по ссылке: CreateLink с download_path дает URL для GET, а папка приходит как .tar; с upload_path — URL, на который байты файла отправляются через PUT. Каждая ссылка работает один раз и ведет прямо на сервер песочницы.

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: Откройте терминал в браузере

CreateLink с terminal дает страницу с шеллом в песочнице, чтобы в нем печатал человек; его command запускает программу вместо шелла, например claude. WebSocket на тот же URL передает байты терминала в обе стороны — для своего собственного терминала.

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:~$

Ссылка истекает через час, если ttl_seconds не говорит иначе, — не больше 86 400 с, — и хранит токен в своем URL: отдайте ее человеку, который будет ею пользоваться, и никогда не размещайте на странице, которую читают другие. Создание ссылки ничего не будит.

Где выполняется команда

Команда выполняется в ВМ песочницы от имени user (uid 1000, sudo без пароля, в группе docker) в /home/user или от имени root. Ее окружение — окружение шаблона, поверх которого лежат переменные самой песочницы (settings.environment). stdin дает ей входные данные, после чего закрывается. Команда работает, пока не завершится, пока не истечет timeout_seconds или пока ее не остановит StopCommand: заканчивается ожидание вызова, а не команда.

Вызов к песочнице на паузе сначала будит ее, примерно за 80 ms. Фоновый процесс, оставленный работать (сервер, запущенный с &), переживает паузы, но сам по себе не дает песочнице уснуть: запускайте долгую задачу с keep_awake, чтобы таймер паузы ее ждал (keep_awake).

Вывод, смещения и история

Ответ содержит последние 32 KiB stdout и stderr в UTF-8, с output_truncated, если начало обрезано, и stdout_bytes и stderr_bytes — сколько всего было записано. exit_code — код шелла: 128 плюс номер сигнала, если команду завершил сигнал, и его нет, пока она идет. Песочница хранит последние 100 завершенных команд для GetCommand. ListCommands перечисляет те, что идут сейчас, запущенные через API, по SSH или в терминале.

StopCommand посылает SIGTERM, а через 10 с — SIGKILL, если команда еще идет. Вызванный для завершенной команды, он убивает то, что она оставила работать в фоне.

Правки точной заменой

edit заменяет old_text на new_text, если old_text встречается в файле ровно один раз; файл — не больше 16 MiB. Если фрагмента нет, это EDIT_NOT_FOUND; если он встречается два раза или больше — EDIT_AMBIGUOUS, и в обоих случаях файл не меняется. Именно такие правки делают агенты для кода, и они громко отказывают там, где номер строки устарел бы незаметно. Запись заменяет файл целиком и сохраняет его владельца и права; через символическую ссылку она пишет в ее цель.

WatchFiles присылает потоком то, что создается, записывается, удаляется и переименовывается в папке, а с recursive — и во вложенных. OVERFLOW говорит, что события потеряны: перечитайте папку.

Docker в песочнице

В каждой песочнице из base есть Docker с Compose и Buildx. Его демон запускается при первом подключении к /var/run/docker.sock и до тех пор ничего не стоит. Образы и контейнеры лежат на диске песочницы, поэтому остановка их сохраняет, а шаблон переносит. Образы с Docker Hub скачиваются сначала через зеркало.

Если не работает

  • Ответ — RUNNING, без кода выхода: команда идет дольше wait_seconds и продолжает работать. Следите за ней через WatchCommand или ждите через GetCommand.
  • Песочница встала на паузу посреди долгой сборки: пока шла сборка, к ней никто не обращался. Запускайте такую работу с keep_awake и timeout_seconds.
  • failure — EDIT_NOT_FOUND или EDIT_AMBIGUOUS: прочитайте файл снова и отправьте old_text, который встречается один раз; изменения перед ним в пачке сделаны (done_count).
  • RESOURCE_EXHAUSTED без LimitReached: запрос вышел за свою границу (файл больше 17 MiB: используйте ссылку для загрузки), или песочница уже обслуживает 64 вызовов одновременно. Завершите один или подождите.
  • FAILED_PRECONDITION со Stopped: песочница остановлена. ResumeSandbox запускает ее, и файлы — такими, какими она их оставила.
  • Команда, которая была RUNNING, стала LOST: песочница потеряла память (остановилась), пока команда шла. Запустите ее снова.

Вопросы

Сколько может идти команда?

Сколько нужно: вызов ждет до 45 с, а команда продолжает работать. Раньше ее завершают только timeout_seconds или StopCommand.

Можно ли выполнять команды от root?

Да: user root или sudo, который есть у user без пароля.

Как загрузить в песочницу большой файл?

CreateLink с upload_path дает URL, на который файл любого размера отправляется через PUT, или это за вас делает pethost sandbox cp.

Можно ли запускать Docker в песочнице?

Да. Docker, Compose и Buildx есть в base, а демон запускается при первом использовании.

Не дает ли работающий фоновый процесс песочнице уснуть?

Нет. Он переживает паузы, и запрос к его порту будит песочницу, но не дают ей встать на паузу только вызовы, сессии и команды с keep_awake.

Попробуйте Pethost Agent Sandboxes

Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.

Начать пробный период