Українська
Меню документації

Документація Agent Sandboxes · Початок

Швидкий старт: ваша перша пісочниця

Оновлено · 10 хв читання

Ваша перша пісочниця за кілька хвилин: установіть 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 чи новіші.

Python
pip install pethost
TypeScript
npm install pethost          # or: bun add pethost
deno add jsr:@pethost/sdk    # Deno: import from "@pethost/sdk/sandboxes"
Go
go get github.com/pethost-dev/sdk/go
Rust
cargo add pethost
cargo add tokio --features macros,rt-multi-thread,time
CLI
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 с на боці сервера плюс ваш шлях до панелі й назад.

Python
from pethost.sandboxes import Sandboxes

sandboxes = Sandboxes()  # reads PETHOST_TOKEN
sandbox = sandboxes.create_sandbox("base")
print(sandbox.sandbox_id, sandbox.state.name)  # 5a4c9z5zw58mvqww RUNNING
TypeScript
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);
Go
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.
}
Rust
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(())
}
HTTP
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 і працює далі: команди й файли пояснюють, як за нею стежити.

Python
command = sandboxes.run_command(sandbox.sandbox_id, command="python3 -c 'print(6 * 7)'")
print(command.exit_code, command.stdout)  # 0 42
TypeScript
const command = await sandboxes.runCommand({ sandboxId, command: "python3 -c 'print(6 * 7)'" });
console.log(command.exitCode, command.stdout); // 0 42
Go
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
Rust
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
HTTP
# 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, а відсутні каталоги створюються.

Python
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')
TypeScript
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);
Go
_, 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))
}
Rust
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>, яку може відкрити будь-хто.

Python
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
TypeScript
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);
Go
_, 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)
Rust
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);
}
MCP
UpdateSandbox {"sandbox_id": "…", "settings": {"ingress": {"public_ports": [{"port": 8000}]}}}

Відкрийте адресу в браузері або через curl: повернеться список файлів каталогу /home/user. Порт, що не є публічним, відповідає лише на запити з токеном для нього: порти й прев’ю.

Дайте їй стати на паузу

Лишіть пісочницю в спокої на 5 хв, і вона стане на паузу: її пам’ять, процеси й диск зберігаються на її сервері за 30% ціни роботи. Наступний виклик, вхід по SSH або запит до її порту будить її приблизно за 0,1 с там, де вона була. Тут її ставлять на паузу одразу, і вебсервер після пробудження досі на місці:

Python
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
TypeScript
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
Go
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
Rust
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
MCP
PauseSandbox {"sandbox_id": "…"}

Після 30 хв простою вона зупиняється: її процеси завершуються, а диск переходить в об’єктне сховище, де коштує 0,03 $ за GiB того, що на ньому, на місяць. ResumeSandbox запускає її знову. Життєвий цикл і простій описує таймери і як їх змінити.

Видаліть її

DeleteSandbox назавжди відкидає пам’ять і диск пісочниці й відповідає її остаточним записом, із тим, що вона використала.

Python
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
TypeScript
const gone = await sandboxes.deleteSandbox({ sandboxId });
console.log(gone.state, gone.usage);
Go
gone, err := client.DeleteSandbox(ctx, &sandboxes.DeleteSandboxRequest{SandboxID: id})
if err != nil {
	log.Fatal(err)
}
fmt.Println(gone.State, *gone.Usage)
Rust
let gone = sandboxes
    .delete_sandbox(DeleteSandboxRequest { sandbox_id: id, ..Default::default() })
    .await?;
println!("{:?} {:?}", gone.state, gone.usage);
MCP
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 $ на місяць, який включає стільки ж використання.

Почати пробний період