Документація Agent Sandboxes · Початок
Швидкий старт: ваша перша пісочниця
Ваша перша пісочниця за кілька хвилин: установіть SDK, створіть API-токен, створіть пісочницю, виконайте в ній команду, запишіть файл, відкрийте порт в інтернет, дайте їй стати на паузу й видаліть її. Кожен крок — один виклик у Python, TypeScript, Go чи Rust, а далі ті самі кроки з CLI pethost.
- Один пакет: SDK, який ви вже знаєте з Pethost, із клієнтом для пісочниць поруч:
pethost.sandboxes,pethost/sandboxes,github.com/pethost-dev/sdk/go/sandboxes,pethost::sandboxes. - Один токен: API-токен у
PETHOST_TOKEN. Сервер кожної пісочниці та її токен клієнт знаходить сам. - Один id: кожен виклик називає свою пісочницю за
sandbox_id. - Нічого не треба прибирати вручну: забута пісочниця стає на паузу через 5 хв і зупиняється через 30.
Установіть SDK
Клієнт пісочниць — частина SDK Pethost кожною мовою, тож одне встановлення дає обидва. Python 3.10, Node 22 (або Bun, або Deno), Go 1.26 і Rust 1.88 чи новіші.
pip install pethost
npm install pethost # or: bun add pethost
deno add jsr:@pethost/sdk # Deno: import from "@pethost/sdk/sandboxes"
go get github.com/pethost-dev/sdk/go
cargo add pethost
cargo add tokio --features macros,rt-multi-thread,time
curl -fsSL https://pethost.dev/install.sh | sh # macOS, Linux
irm https://pethost.dev/install.ps1 | iex # Windows, in PowerShell
Створіть API-токен
Step 1: Створіть робочий простір Agent Sandboxes
Увійдіть на console.pethost.dev і створіть робочий простір, вибравши Agent Sandboxes. Перший простір нового акаунта починається з пробного періоду: 7 днів, використання на 1 $ і 4 vCPU, потрібна картка.
Step 2: Створіть для нього токен
У робочому просторі відкрийте Підключити агента або свій код і натисніть Створити API-токен. Токен починається з pth_, відкриває лише цей робочий простір і показується один раз. Список ваших токенів — у «Налаштуваннях» акаунта, там їх і відкликають.
Step 3: Передайте його програмі
export PETHOST_TOKEN=pth_...
Клієнт Python і CLI читають його із середовища; програми нижче передають його клієнтам TypeScript, Go і Rust. Не тримайте його в коді: він діє від імені вашого акаунта.
Створіть пісочницю
Пісочниця стартує із шаблону. Наш, base, — це Ubuntu 24.04 з Python, Node.js, Docker, трьома агентами для коду й Chrome. CreateSandbox відповідає, щойно пісочниця запрацює: приблизно за 0,15 с на боці сервера плюс ваш шлях до панелі й назад.
from pethost.sandboxes import Sandboxes
sandboxes = Sandboxes() # reads PETHOST_TOKEN
sandbox = sandboxes.create_sandbox("base")
print(sandbox.sandbox_id, sandbox.state.name) # 5a4c9z5zw58mvqww RUNNING
import { Sandboxes } from "pethost/sandboxes";
const sandboxes = new Sandboxes({ token: process.env.PETHOST_TOKEN! });
const sandbox = await sandboxes.createSandbox({ template: "base" });
const sandboxId = sandbox.sandboxId;
console.log(sandboxId, sandbox.state);
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/pethost-dev/sdk/go/sandboxes"
)
func main() {
ctx := context.Background()
client := sandboxes.NewClient(sandboxes.Config{Token: os.Getenv("PETHOST_TOKEN")})
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "base"})
if err != nil {
log.Fatal(err)
}
id := sandbox.SandboxID
fmt.Println(id, sandbox.State)
// The next steps go on here.
}
use pethost::sandboxes::{types::*, Client};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let sandboxes = Client::new(&std::env::var("PETHOST_TOKEN")?);
let sandbox = sandboxes
.create_sandbox(CreateSandboxRequest { template: "base".into(), ..Default::default() })
.await?;
let id = sandbox.sandbox_id.clone();
println!("{id} {:?}", sandbox.state);
// The next steps go on here.
Ok(())
}
curl -s https://console.pethost.dev/pethost.sandboxes.v1.SandboxService/CreateSandbox \
-H "Authorization: Bearer $PETHOST_TOKEN" -H "Content-Type: application/json" \
-d '{"template": "base"}'
# {"sandbox_id": "w86eeaozgndh3gj2", "state": "SANDBOX_STATE_RUNNING", "template": "base@17", …,
# "connection": {"url": "https://sbx1.sandboxes.pethost.network", "token": "…", …}}
Збережіть id: кожен інший виклик називає пісочницю за ним. Пісочниці можна також дати name, унікальну в робочому просторі назву, за якою її знаходить ListSandboxes.
Виконайте команду
RunCommand виконує команду оболонки від імені користувача user у /home/user і відповідає, коли вона завершиться, з її кодом виходу й останніми 32 KiB її виводу. Команда, що триває довше за 45 с, відповідає RUNNING і працює далі: команди й файли пояснюють, як за нею стежити.
command = sandboxes.run_command(sandbox.sandbox_id, command="python3 -c 'print(6 * 7)'")
print(command.exit_code, command.stdout) # 0 42
const command = await sandboxes.runCommand({ sandboxId, command: "python3 -c 'print(6 * 7)'" });
console.log(command.exitCode, command.stdout); // 0 42
command, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: "python3 -c 'print(6 * 7)'"})
if err != nil {
log.Fatal(err)
}
fmt.Println(*command.ExitCode, command.Stdout) // 0 42
let command = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "python3 -c 'print(6 * 7)'".into(),
..Default::default()
})
.await?;
println!("{:?} {}", command.exit_code, command.stdout); // Some(0) 42
# URL and TOKEN: connection.url and connection.token of the create's answer
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"sandbox_id": "'"$ID"'", "command": "python3 -c '\''print(6 * 7)'\''"}'
# {"commandId": "efpe95t24evu", "state": "COMMAND_STATE_EXITED", "exitCode": 0, "stdout": "42\n", …}
Команда пішла на власний сервер пісочниці, а не на панель. SDK узяв адресу сервера й токен для цієї пісочниці з відповіді на створення і сам просить нові, коли вони спливають.
Запишіть і прочитайте файл
WriteFiles вносить зміни по черзі, одним викликом: записує файли цілком, редагує файл точною заміною, переміщує й видаляє. Шляхи абсолютні або відносні до /home/user, а відсутні каталоги створюються.
from pethost.sandboxes import FileChange, TextEdit
sandboxes.write_files(sandbox.sandbox_id, changes=[
FileChange(path="app/hello.py", text="print('hello')\n"),
FileChange(path="app/hello.py", edit=TextEdit(old_text="hello", new_text="hello, sandbox")),
])
print(sandboxes.read_file(sandbox.sandbox_id, path="app/hello.py").text) # print('hello, sandbox')
await sandboxes.writeFiles({
sandboxId,
changes: [
{ path: "app/hello.py", text: "print('hello')\n" },
{ path: "app/hello.py", edit: { oldText: "hello", newText: "hello, sandbox" } },
],
});
const file = await sandboxes.readFile({ sandboxId, path: "app/hello.py" });
console.log(file.text);
_, err = client.WriteFiles(ctx, &sandboxes.WriteFilesRequest{SandboxID: id, Changes: []sandboxes.FileChange{
{Path: "app/hello.py", Change: sandboxes.FileChangeText("print('hello')\n")},
{Path: "app/hello.py", Change: sandboxes.FileChangeEdit{OldText: "hello", NewText: "hello, sandbox"}},
}})
if err != nil {
log.Fatal(err)
}
file, err := client.ReadFile(ctx, &sandboxes.ReadFileRequest{SandboxID: id, Path: "app/hello.py"})
if err != nil {
log.Fatal(err)
}
if text, ok := file.Content.(sandboxes.FileText); ok {
fmt.Print(string(text))
}
let write = |change| FileChange { path: "app/hello.py".into(), change: Some(change), ..Default::default() };
sandboxes
.write_files(WriteFilesRequest {
sandbox_id: id.clone(),
changes: vec![
write(FileChangeChange::Text("print('hello')\n".into())),
write(FileChangeChange::Edit(TextEdit { old_text: "hello".into(), new_text: "hello, sandbox".into() })),
],
})
.await?;
let file = sandboxes
.read_file(ReadFileRequest { sandbox_id: id.clone(), path: "app/hello.py".into(), ..Default::default() })
.await?;
if let Some(FileContent::Text(text)) = file.content {
print!("{text}");
}
Зміна, що не вдалася, зупиняє пакет, а відповідь каже, скільки змін виконано й чому наступна не вдалася (failure): правка, чийого old_text немає у файлі або який трапляється двічі, нічого не змінює.
Відкрийте порт в інтернет
Запустіть сервер із wait_for_port: виклик відповідає, щойно щось слухає порт, а сервер працює далі. Потім зробіть порт публічним. Він отримає власну адресу, https://<port>-<sandbox id>.<server>, яку може відкрити будь-хто.
from pethost.sandboxes import Ingress, PublicPort, SandboxSettings
sandboxes.run_command(sandbox.sandbox_id, command="python3 -m http.server 8000", wait_for_port=8000)
sandbox = sandboxes.update_sandbox(
sandbox.sandbox_id,
settings=SandboxSettings(ingress=Ingress(public_ports=[PublicPort(port=8000)])),
)
print(sandbox.settings.ingress.public_ports[0].url)
# https://8000-5a4c9z5zw58mvqww.sbx1.sandboxes.pethost.network
await sandboxes.runCommand({ sandboxId, command: "python3 -m http.server 8000", waitForPort: 8000 });
const updated = await sandboxes.updateSandbox({
sandboxId,
settings: { ingress: { publicPorts: [{ port: 8000 }] } },
});
console.log(updated.settings?.ingress?.publicPorts[0]?.url);
_, err = client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: "python3 -m http.server 8000", WaitForPort: 8000})
if err != nil {
log.Fatal(err)
}
updated, err := client.UpdateSandbox(ctx, &sandboxes.UpdateSandboxRequest{SandboxID: id, Settings: &sandboxes.SandboxSettings{
Ingress: &sandboxes.Ingress{PublicPorts: []sandboxes.PublicPort{{Port: 8000}}},
}})
if err != nil {
log.Fatal(err)
}
fmt.Println(updated.Settings.Ingress.PublicPorts[0].URL)
sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "python3 -m http.server 8000".into(),
wait_for_port: 8000,
..Default::default()
})
.await?;
let ingress = Ingress { public_ports: vec![PublicPort { port: 8000, ..Default::default() }] };
let updated = sandboxes
.update_sandbox(UpdateSandboxRequest {
sandbox_id: id.clone(),
settings: Some(SandboxSettings { ingress: Some(ingress), ..Default::default() }),
..Default::default()
})
.await?;
if let Some(ingress) = updated.settings.and_then(|settings| settings.ingress) {
println!("{}", ingress.public_ports[0].url);
}
UpdateSandbox {"sandbox_id": "…", "settings": {"ingress": {"public_ports": [{"port": 8000}]}}}
Відкрийте адресу в браузері або через curl: повернеться список файлів каталогу /home/user. Порт, що не є публічним, відповідає лише на запити з токеном для нього: порти й прев’ю.
Дайте їй стати на паузу
Лишіть пісочницю в спокої на 5 хв, і вона стане на паузу: її пам’ять, процеси й диск зберігаються на її сервері за 30% ціни роботи. Наступний виклик, вхід по SSH або запит до її порту будить її приблизно за 0,1 с там, де вона була. Тут її ставлять на паузу одразу, і вебсервер після пробудження досі на місці:
print(sandboxes.pause_sandbox(sandbox.sandbox_id).state.name) # PAUSED
check = sandboxes.run_command(sandbox.sandbox_id, command="curl -s -o /dev/null -w '%{http_code}' localhost:8000")
print(check.stdout) # 200: the server ran on through the pause
print(sandboxes.get_sandbox(sandbox.sandbox_id).state.name) # RUNNING
console.log((await sandboxes.pauseSandbox({ sandboxId })).state); // PAUSED
const check = await sandboxes.runCommand({
sandboxId,
command: "curl -s -o /dev/null -w '%{http_code}' localhost:8000",
});
console.log(check.stdout); // 200: the server ran on through the pause
console.log((await sandboxes.getSandbox({ sandboxId })).state); // RUNNING
paused, err := client.PauseSandbox(ctx, &sandboxes.PauseSandboxRequest{SandboxID: id})
if err != nil {
log.Fatal(err)
}
fmt.Println(paused.State) // PAUSED
check, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
SandboxID: id,
Command: "curl -s -o /dev/null -w '%{http_code}' localhost:8000",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(check.Stdout) // 200: the server ran on through the pause
let paused = sandboxes
.pause_sandbox(PauseSandboxRequest { sandbox_id: id.clone(), ..Default::default() })
.await?;
println!("{:?}", paused.state); // Paused
let check = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "curl -s -o /dev/null -w '%{http_code}' localhost:8000".into(),
..Default::default()
})
.await?;
println!("{}", check.stdout); // 200: the server ran on through the pause
PauseSandbox {"sandbox_id": "…"}
Після 30 хв простою вона зупиняється: її процеси завершуються, а диск переходить в об’єктне сховище, де коштує 0,03 $ за GiB того, що на ньому, на місяць. ResumeSandbox запускає її знову. Життєвий цикл і простій описує таймери і як їх змінити.
Видаліть її
DeleteSandbox назавжди відкидає пам’ять і диск пісочниці й відповідає її остаточним записом, із тим, що вона використала.
gone = sandboxes.delete_sandbox(sandbox.sandbox_id)
print(gone.state.name, gone.usage)
# DELETED Usage(running_seconds=11, paused_seconds=0, stored_gib_hours=0.0, cost_micros=0)
# cost_micros is what was charged so far: its last seconds are charged a moment later,
# and get_sandbox(sandbox.sandbox_id).usage then says cost_micros=110
const gone = await sandboxes.deleteSandbox({ sandboxId });
console.log(gone.state, gone.usage);
gone, err := client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: id})
if err != nil {
log.Fatal(err)
}
fmt.Println(gone.State, *gone.Usage)
let gone = sandboxes
.delete_sandbox(DeleteSandboxRequest { sandbox_id: id, ..Default::default() })
.await?;
println!("{:?} {:?}", gone.state, gone.usage);
DeleteSandbox {"sandbox_id": "…"}
Те саме з CLI pethost
pethost sandbox, або pethost sbx, робить кожен із цих кроків із термінала, через Go SDK. Назва пісочниці працює всюди, де працює її id.
Step 1: Увійдіть
$ pethost login
Вхід відбувається у вашому браузері. У скрипті натомість задайте PETHOST_TOKEN.
Step 2: Створіть пісочницю
$ pethost sandbox new --name api-dev
✓ Made sandbox api-dev (exdei47yr5je70v5): default, running, from base@17, in <1 s
exdei47yr5je70v5
Next: pethost sandbox run exdei47yr5je70v5 -- <command> · pethost sandbox shell exdei47yr5je70v5
id виводиться окремо в stdout, тож id=$(pethost sandbox new) його зберігає.
Step 3: Виконайте команду й скопіюйте файли всередину
$ pethost sandbox run api-dev -- python3 -c 'print(6 * 7)'
42
$ pethost sandbox cp ./app api-dev:app
✓ Copied ./app to exdei47yr5je70v5:app · 2 KB in <1 s
Step 4: Відкрийте порт
$ pethost sandbox run api-dev -d --wait-for-port 8000 -- python3 -m http.server 8000
It runs on in the sandbox. Its output so far: pethost api GetCommand '{"sandbox_id": "exdei47yr5je70v5", "command_id": "5f2mo5wikluq"}'
5f2mo5wikluq
$ pethost sandbox ports api-dev --open 8000
8000 https://8000-exdei47yr5je70v5.sbx1.sandboxes.pethost.network
Step 5: Поставте її на паузу й видаліть
$ pethost sandbox pause api-dev
exdei47yr5je70v5 paused
$ pethost sandbox rm api-dev --yes
exdei47yr5je70v5 deleted
Якщо робочих просторів пісочниць кілька, назвіть потрібний через -w. Довідник CLI описує кожну команду.
Те саме через вашого агента
Агент, що говорить MCP, отримує пісочниці як інструменти: додайте https://mcp.pethost.dev/sandboxes у Claude Code, Codex, Cursor чи Claude, увійдіть у браузері й попросіть його щось запустити в пісочниці. Підключення агента описує кроки для кожного.
Що клієнт робить за вас
Відповідають два сервіси. Панель, на console.pethost.dev, зберігає запис кожної пісочниці: створення, налаштування, пауза, копіювання, видалення. Власний сервер пісочниці виконує те, що відбувається всередині: команди, файли, робочий стіл, посилання й агентів для коду. Виклику другого типу потрібні адреса цього сервера й токен лише для цієї пісочниці. Клієнт бере обидва з відповіді CreateSandbox чи ForkSandbox або просить їх у ConnectSandbox, тримає їх до моменту незадовго до спливання й один раз просить знову, коли сервер їх відхиляє. Ваш API-токен ніколи не потрапляє на сервер пісочниці.
Виклик, що щось створює, приймає request_id. Клієнт TypeScript дає його кожному виклику, якщо ви його пропустили, і зберігає, коли повторює виклик через нове з’єднання, тож сервер виконує його один раз. Надсилайте власний і надсилайте його знову, коли повторюєте виклик після втраченої відповіді: повтор відповідає тим, що зробив перший виклик, протягом 24 год.
У якому робочому просторі діє виклик
Виклик, що називає пісочницю, діє в робочому просторі цієї пісочниці. Будь-який інший виклик діє в робочому просторі, який називає його запит (workspace, за id чи назвою), інакше — у тому, з яким створено клієнт, інакше — у вашому єдиному робочому просторі пісочниць. Якщо токен відкриває кілька, а виклик жодного не називає, його відхиляють із WorkspaceChoice, що їх перелічує.
Коли не працює
FAILED_PRECONDITIONзWorkspaceChoice: токен відкриває кілька робочих просторів пісочниць. Назвіть один:Sandboxes(workspace="..."),workspaceу запиті або-wдля CLI.PERMISSION_DENIEDнаCreateSandbox: токену не надано цей робочий простір. Створіть токен у власному Підключити агента або свій код цього робочого простору або надайте доступ у «Налаштуваннях».UNAUTHENTICATED: токена немає, його введено з помилкою або відкликано. ПеревіртеPETHOST_TOKENв оболонці, що запускає програму.RESOURCE_EXHAUSTEDзLimitReached,vcpus: пісочниці робочого простору тримають усі його vCPU, і ті, що працюють, і ті, що на паузі. У пробному періоді їх 4: одна пісочниця DEFAULT або дві SMALL. Видаліть чи зупиніть одну або попросітьSMALL.RESOURCE_EXHAUSTEDзLimitReached,starts_per_minute,_hourчи_day: забагато запусків у цьому вікні. Запуски безкоштовні, але обмежені:retry_timeкаже, коли виклик вміститься. Ліміти наводять ліміти кожного тарифу.- Команда відповідає RUNNING: вона тривала довше за 45 с і працює далі.
GetCommandз їїcommand_idчекає знову.
Помилки перелічують кожну відмову і що з нею робити.
Запитання
Чи потрібен окремий SDK для пісочниць?
Ні. Клієнт пісочниць — частина SDK Pethost для Python, TypeScript, Go і Rust: установіть pethost та імпортуйте його модуль пісочниць.
Де взяти API-токен?
У панелі, у вашому робочому просторі пісочниць: «Підключити агента або свій код», потім «Створити API-токен». Він починається з pth_ і показується один раз.
Чи є безкоштовний пробний період?
Так: 7 днів, використання на 1 $ і 4 vCPU, для першого робочого простору пісочниць нового акаунта. Потрібна картка.
Що буде, якщо я забуду пісочницю?
Вона стане на паузу після 5 хв простою і зупиниться після 30, тож коштуватиме лише її збережені дані. Вона ніколи не видаляється, якщо ви її не видалите або не задасте delete_after_idle_seconds.
Чи можна викликати API без SDK?
Так. Обидва сервіси говорять Connect, gRPC і gRPC-Web: POST із JSON на /pethost.sandboxes.v1.SandboxService/<Method> з вашим токеном працює, а довідник API описує кожне поле.
Спробуйте Pethost Agent Sandboxes
Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.