Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Pierwsze kroki

Szybki start: twój pierwszy sandbox

Zaktualizowano · 10 min czytania

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.

W skrócie
  • 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.

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

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.

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": "…", …}}

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ć.

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", …}

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.

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}");
}

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ć.

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}]}}}

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:

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": "…"}

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ł.

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": "…"}

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_PRECONDITION z WorkspaceChoice: token sięga kilku przestrzeni roboczych z sandboxami. Wskaż jedną: Sandboxes(workspace="..."), workspace w żądaniu albo -w w CLI.
  • PERMISSION_DENIED przy CreateSandbox: 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_TOKEN w powłoce, która uruchamia program.
  • RESOURCE_EXHAUSTED z LimitReached, 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ś o SMALL.
  • RESOURCE_EXHAUSTED z LimitReached, starts_per_minute, _hour albo _day: za dużo startów w tym oknie. Starty są darmowe i ograniczone: retry_time mó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. GetCommand z jego command_id czeka 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.

Zacznij okres próbny