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

Документация 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 $ в месяц, в который входит столько же использования.

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