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