---
title: "Виконуйте команди й редагуйте файли в пісочниці | Pethost Agent Sandboxes"
description: "Виконуйте команди оболонки в пісочниці й чекайте виводу чи порту, транслюйте довгі, редагуйте файли точною заміною й передавайте великі файли через посилання."
---

[Документація Agent Sandboxes](https://pethost.dev/uk/docs/sandboxes/) · Завдання

# Виконуйте команди й редагуйте файли в пісочниці

Оновлено 22 листопада 2026 р. · 8 хв читання

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

**Коротко**

- **`RunCommand`** виконує `bash -lc` від імені `user` у `/home/user` і чекає до 45 с: код виходу й останні 32 KiB виводу або RUNNING з її id.
- **`WatchCommand`** транслює вивід команди в міру появи; `GetCommand` чекає знову й читає лише нове.
- **`WriteFiles`** записує, редагує, переміщує й видаляє файли одним викликом, по черзі; правка замінює текст, що трапляється рівно один раз.
- **Посилання** передають файли будь-якого розміру й відкривають термінал у браузері.

Приклади продовжують [швидкий старт](https://pethost.dev/uk/docs/sandboxes/quickstart/): `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](https://pethost.dev/uk/docs/sandboxes/lifecycle/#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](https://pethost.dev/uk/docs/sandboxes/best-practices/) [ДаліПорти й прев’ю: URL пісочниці](https://pethost.dev/uk/docs/sandboxes/ports-and-previews/)

## Спробуйте Pethost Agent Sandboxes

Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.

[Почати пробний період](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Шаблони](https://pethost.dev/uk/templates/)
- [Про нас](https://pethost.dev/about/)
- [Документація](https://pethost.dev/docs/)
- [Блог](https://pethost.dev/uk/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Плагін](https://github.com/pethost-dev/plugin)
- [Умови](https://pethost.dev/terms/)
- [Конфіденційність](https://pethost.dev/privacy/)
- [Повернення коштів](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Бази даних

- [Postgres](https://pethost.dev/uk/postgres/)
- [Valkey](https://pethost.dev/uk/valkey/)

Agent Sandboxes

- [Пісочниці](https://pethost.dev/uk/sandboxes/)
- [Тарифи](https://pethost.dev/uk/sandboxes/#pricing)
- [Документація](https://pethost.dev/uk/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Порівняння

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/uk/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/uk/blog/coolify-cloud-vs-dokploy-cloud/)
- [Ціни Railway vs Render vs Fly.io](https://pethost.dev/uk/blog/railway-vs-render-vs-fly-io-pricing/)
- [Керований хостинг Docker Compose](https://pethost.dev/uk/blog/managed-docker-compose-hosting/)

Альтернативи

- [Альтернативи Railway](https://pethost.dev/uk/blog/railway-alternatives/)
- [Альтернативи Heroku](https://pethost.dev/uk/blog/heroku-alternatives/)
- [Альтернативи Dokploy](https://pethost.dev/uk/blog/dokploy-alternatives/)
- [Альтернативи Coolify](https://pethost.dev/uk/blog/coolify-alternatives/)
- [Альтернативи Render](https://pethost.dev/uk/blog/render-alternatives/)
- [Альтернативи Sliplane](https://pethost.dev/uk/blog/sliplane-alternatives/)
