Dokumentacja Agent Sandboxes · Pierwsze kroki
Szybki start: twój pierwszy sandbox
Twój pierwszy sandbox w kilka minut: zainstaluj SDK, utwórz token API, utwórz sandbox, uruchom w nim polecenie, zapisz plik, otwórz port na internet, pozwól mu się wstrzymać i go usuń. Każdy krok to jedno wywołanie, w Pythonie, TypeScripcie, Go albo Ruście, a dalej te same kroki z CLI pethost.
- Jeden pakiet: SDK, które już znasz z Pethost, z klientem sandboxów obok:
pethost.sandboxes,pethost/sandboxes,github.com/pethost-dev/sdk/go/sandboxes,pethost::sandboxes. - Jeden token: token API w
PETHOST_TOKEN. Klient sam znajduje serwer każdego sandboxa i jego token. - Jedno id: każde wywołanie wskazuje sandbox przez
sandbox_id. - Nic do sprzątania ręcznie: zapomniany sandbox wstrzymuje się po 5 minutach i zatrzymuje po 30.
Zainstaluj SDK
Klient sandboxów jest częścią SDK Pethost w każdym języku, więc jedna instalacja daje ci oba. Python 3.10, Node 22 (albo Bun czy Deno), Go 1.26 i Rust 1.88 lub nowsze.
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
Utwórz token API
Step 1: Utwórz przestrzeń roboczą Agent Sandboxes
Zaloguj się na console.pethost.dev i utwórz przestrzeń roboczą, wybierając Agent Sandboxes. Pierwsza na nowym koncie zaczyna się od okresu próbnego: 7 dni z 1 $ zużycia i 4 vCPU, potrzebna jest karta.
Step 2: Utwórz dla niej token
W przestrzeni roboczej otwórz Podłącz agenta lub swój kod i naciśnij Utwórz token API. Token zaczyna się od pth_, działa tylko w tej przestrzeni roboczej i jest pokazywany raz. Twoje tokeny są wymienione, i tam je unieważniasz, w Ustawieniach konta.
Step 3: Przekaż go swojemu programowi
export PETHOST_TOKEN=pth_...
Klient Pythona i CLI czytają go ze środowiska; programy poniżej przekazują go klientom TypeScriptu, Go i Rusta. Nie trzymaj go w kodzie: działa jako twoje konto.
Utwórz sandbox
Sandbox startuje z szablonu. Nasz, base, to Ubuntu 24.04 z Pythonem, Node.js, Dockerem, trzema agentami kodującymi i Chrome. CreateSandbox odpowiada, gdy sandbox już działa, w ok. 0,15 s po stronie serwera, plus twoja droga do panelu i z powrotem.
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": "…", …}}
Zachowaj id: każde inne wywołanie wskazuje nim sandbox. Możesz też dać sandboxowi name, unikalne w przestrzeni roboczej, po którym znajdzie go ListSandboxes.
Uruchom polecenie
RunCommand uruchamia polecenie powłoki jako użytkownik user w /home/user i odpowiada, gdy się skończy, z kodem wyjścia i ostatnimi 32 KiB wyjścia. Polecenie, które trwa dłużej niż 45 s, odpowiada RUNNING i działa dalej: polecenia i pliki mówią, jak je śledzić.
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", …}
Polecenie poszło do serwera samego sandboxa, nie do panelu. SDK wzięło adres serwera i token dla tego sandboxa z odpowiedzi na utworzenie, a gdy wygasną, samo poprosi o nowe.
Zapisz i odczytaj plik
WriteFiles wprowadza zmiany po kolei, w jednym wywołaniu: zapisuje całe pliki, edytuje plik przez dokładną zamianę, przenosi i usuwa. Ścieżki są bezwzględne albo względne wobec /home/user, a brakujące katalogi powstają same.
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}");
}
Zmiana, która się nie uda, zatrzymuje paczkę, a odpowiedź mówi, ile wykonano i dlaczego następna się nie udała (failure): edycja, której old_text nie ma w pliku albo jest w nim dwa razy, niczego nie zmienia.
Otwórz port na internet
Uruchom serwer z wait_for_port: wywołanie odpowiada, gdy tylko coś nasłuchuje na porcie, a serwer działa dalej. Potem udostępnij port publicznie. Dostaje własny adres, https://<port>-<sandbox id>.<server>, który każdy może otworzyć.
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}]}}}
Otwórz adres w przeglądarce albo przez curl: wraca lista plików katalogu /home/user. Port, który nie jest publiczny, odpowiada tylko na żądania z tokenem do niego: porty i podglądy.
Pozwól mu się wstrzymać
Zostaw sandbox w spokoju na 5 minut, a się wstrzyma: jego pamięć, procesy i dysk zostają na jego serwerze, za 30% ceny działania. Następne wywołanie, logowanie SSH albo żądanie do jego portu budzi go w ok. 0,1 s tam, gdzie był. Tutaj wstrzymujemy go od razu, a serwer WWW wciąż jest na miejscu po wybudzeniu:
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": "…"}
Po 30 min bezczynności się zatrzymuje: jego procesy się kończą, a dysk trafia do magazynu obiektów, gdzie kosztuje 0,03 $ miesięcznie za GiB danych. ResumeSandbox uruchamia go ponownie. Cykl życia i bezczynność opisuje liczniki i ich zmianę.
Usuń go
DeleteSandbox na dobre usuwa pamięć i dysk sandboxa i odpowiada jego ostatecznym zapisem, z tym, co zużył.
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": "…"}
To samo z CLI pethost
pethost sandbox, czyli pethost sbx, robi każdy z tych kroków z terminala, przez SDK Go. Nazwa sandboxa działa wszędzie tam, gdzie jego id.
Step 1: Zaloguj się
$ pethost login
Logowanie odbywa się w przeglądarce. W skrypcie ustaw zamiast tego PETHOST_TOKEN.
Step 2: Utwórz sandbox
$ 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 jest wypisywane samo na stdout, więc id=$(pethost sandbox new) je zachowa.
Step 3: Uruchom polecenie i skopiuj pliki do środka
$ 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: Otwórz port
$ 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: Wstrzymaj go i usuń
$ pethost sandbox pause api-dev
exdei47yr5je70v5 paused
$ pethost sandbox rm api-dev --yes
exdei47yr5je70v5 deleted
Przy kilku przestrzeniach roboczych z sandboxami wskaż jedną przez -w. Referencja CLI opisuje każde polecenie.
To samo przez agenta
Agent, który mówi MCP, dostaje sandboxy jako narzędzia: dodaj https://mcp.pethost.dev/sandboxes do Claude Code, Codexa, Cursora albo Claude’a, zaloguj się w przeglądarce i poproś go, żeby coś uruchomił w sandboxie. Podłączanie agenta ma kroki dla każdego z nich.
Co klient robi za ciebie
Odpowiadają dwie usługi. Panel, pod console.pethost.dev, trzyma zapis każdego sandboxa: tworzenie, ustawienia, wstrzymanie, fork, usuwanie. Serwer samego sandboxa wykonuje to, co dzieje się w środku: polecenia, pliki, pulpit, linki i agentów kodujących. Wywołanie drugiego rodzaju potrzebuje adresu tego serwera i tokena dla tego jednego sandboxa. Klient bierze oba z odpowiedzi CreateSandbox albo ForkSandbox albo prosi o nie ConnectSandbox, trzyma je do chwili tuż przed wygaśnięciem i prosi ponownie raz, gdy serwer je odrzuci. Twój token API nigdy nie trafia do serwera sandboxa.
Wywołanie, które coś tworzy, przyjmuje request_id. Klient TypeScriptu nadaje go każdemu wywołaniu, gdy go pominiesz, i zachowuje, gdy powtarza wywołanie przy nowym połączeniu, więc serwer wykonuje je raz. Wysyłaj własne i wysyłaj je ponownie, gdy ponawiasz po zgubionej odpowiedzi: ponowienie odpowiada tym, co zrobiło pierwsze wywołanie, przez 24 h.
W której przestrzeni roboczej działa wywołanie
Wywołanie, które wskazuje sandbox, działa w przestrzeni roboczej tego sandboxa. Każde inne działa w przestrzeni roboczej wskazanej w żądaniu (workspace, przez id albo nazwę), a bez niej w tej, z którą utworzono klienta, a bez niej w twojej jedynej przestrzeni roboczej z sandboxami. Gdy token sięga kilku, a wywołanie żadnej nie wskazuje, jest odrzucane z WorkspaceChoice, które je wymienia.
Gdy to nie działa
FAILED_PRECONDITIONzWorkspaceChoice: token sięga kilku przestrzeni roboczych z sandboxami. Wskaż jedną:Sandboxes(workspace="..."),workspacew żądaniu albo-ww CLI.PERMISSION_DENIEDprzyCreateSandbox: token nie ma dostępu do tej przestrzeni roboczej. Utwórz go w jej własnym Podłącz agenta lub swój kod albo daj mu dostęp w Ustawieniach.UNAUTHENTICATED: tokena brakuje, ma literówkę albo został unieważniony. SprawdźPETHOST_TOKENw powłoce, która uruchamia program.RESOURCE_EXHAUSTEDzLimitReached,vcpus: sandboxy przestrzeni roboczej zajmują wszystkie jej vCPU, zarówno działające, jak i wstrzymane. Okres próbny ma 4: jeden sandbox DEFAULT albo dwa SMALL. Usuń albo zatrzymaj któryś albo poproś oSMALL.RESOURCE_EXHAUSTEDzLimitReached,starts_per_minute,_houralbo_day: za dużo startów w tym oknie. Starty są darmowe i ograniczone:retry_timemówi, kiedy wywołanie się zmieści. Limity podają limity każdego planu.- Polecenie odpowiada RUNNING: trwało dłużej niż 45 s i działa dalej.
GetCommandz jegocommand_idczeka ponownie.
Błędy wymieniają każdą odmowę i co zrobić.
Pytania
Czy potrzebuję osobnego SDK do sandboxów?
Nie. Klient sandboxów jest częścią SDK Pethost w Pythonie, TypeScripcie, Go i Ruście: zainstaluj pethost i zaimportuj jego moduł sandboxów.
Skąd wziąć token API?
W panelu, w twojej przestrzeni roboczej z sandboxami: Podłącz agenta lub swój kod, potem Utwórz token API. Zaczyna się od pth_ i jest pokazywany raz.
Czy jest darmowy okres próbny?
Tak: 7 dni z 1 $ zużycia i 4 vCPU, dla pierwszej przestrzeni roboczej z sandboxami na nowym koncie. Potrzebna jest karta.
Co się stanie, jeśli zapomnę o sandboxie?
Wstrzyma się po 5 min bezczynności i zatrzyma po 30, więc kosztuje tylko przechowywane dane. Nigdy nie jest usuwany, chyba że go usuniesz albo ustawisz delete_after_idle_seconds.
Czy mogę wywoływać API bez SDK?
Tak. Obie usługi mówią Connect, gRPC i gRPC-Web: działa POST z JSON-em na /pethost.sandboxes.v1.SandboxService/<Method> z twoim tokenem, a referencja API opisuje każde pole.
Wypróbuj Pethost Agent Sandboxes
Okres próbny na 7 dni z 1 $ zużycia i 4 vCPU, z kartą. Potem plan od 20 $ miesięcznie, który zawiera tyle samo zużycia.