Português
Menu da documentação

Docs do Agent Sandboxes · Começar

Início rápido: o seu primeiro sandbox

Atualizado em · 11 min de leitura

O seu primeiro sandbox em poucos minutos: instale um SDK, crie um token de API, crie um sandbox, rode um comando nele, grave um arquivo, abra uma porta para a internet, deixe-o pausar e exclua-o. Cada passo é uma chamada, em Python, TypeScript, Go ou Rust, e os mesmos passos vêm depois com a CLI pethost.

Em resumo
  • Um pacote: o SDK do Pethost que você já conhece, com um cliente para sandboxes ao lado: pethost.sandboxes, pethost/sandboxes, github.com/pethost-dev/sdk/go/sandboxes, pethost::sandboxes.
  • Um token: um token de API em PETHOST_TOKEN. O cliente encontra sozinho o servidor de cada sandbox e o token dele.
  • Um id: toda chamada nomeia o sandbox pelo sandbox_id.
  • Nada para limpar manualmente: um sandbox esquecido pausa depois de 5 minutos e para depois de 30.

Instale um SDK

O cliente de sandboxes faz parte do SDK do Pethost em cada linguagem, então uma instalação dá os dois. Python 3.10, Node 22 (ou Bun, ou Deno), Go 1.26 e Rust 1.88 ou mais recentes.

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

Crie um token de API

Step 1: Crie um espaço de trabalho do Agent Sandboxes

Entre em console.pethost.dev e crie um espaço de trabalho, escolhendo Agent Sandboxes. O primeiro de uma conta nova começa com um teste grátis: 7 dias com US$ 1 de uso e 4 vCPUs, com cartão obrigatório.

Step 2: Crie um token para ele

No espaço de trabalho, abra Conectar um agente ou seu código e clique em Criar um token de API. O token começa com pth_, só acessa este espaço de trabalho e é mostrado uma vez. Os seus tokens ficam listados, e são revogados, nas Configurações da sua conta.

Step 3: Entregue-o ao seu programa

export PETHOST_TOKEN=pth_...

O cliente Python e a CLI o leem do ambiente; os programas abaixo o passam aos clientes TypeScript, Go e Rust. Mantenha-o fora do seu código: ele age como a sua conta.

Crie um sandbox

Um sandbox inicia a partir de um template. O nosso, base, é Ubuntu 24.04 com Python, Node.js, Docker, três agentes de código e Chrome. CreateSandbox responde assim que o sandbox está rodando, em cerca de 0,15 s do lado do servidor, mais a sua ida e volta ao painel.

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

Guarde o id: todas as outras chamadas nomeiam o sandbox por ele. Você também pode dar ao sandbox um name, único no espaço de trabalho, pelo qual ListSandboxes o encontra.

Rode um comando

RunCommand roda um comando de shell como o usuário user em /home/user e responde quando ele termina, com o código de saída e os últimos 32 KiB da saída. Um comando que leva mais de 45 s responde RUNNING e continua: comandos e arquivos diz como acompanhá-lo.

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

O comando foi para o servidor do próprio sandbox, não para o painel. O SDK pegou o endereço do servidor e um token para este sandbox da resposta da criação, e pede novos sozinho quando eles expiram.

Grave e leia um arquivo

WriteFiles faz alterações em ordem, em uma chamada: grava arquivos inteiros, edita um por substituição exata, move e exclui. Os caminhos são absolutos, ou relativos a /home/user, e diretórios que faltam são criados.

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

Uma alteração que falha interrompe o lote, e a resposta diz quantas foram feitas e por que a seguinte falhou (failure): uma edição cujo old_text não está no arquivo, ou está duas vezes, não muda nada.

Abra uma porta para a internet

Inicie um servidor com wait_for_port: a chamada responde assim que algo escuta na porta, enquanto o servidor continua rodando. Depois torne a porta pública. Ela ganha um endereço próprio, https://<port>-<sandbox id>.<server>, que qualquer pessoa pode abrir.

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

Abra o endereço em um navegador, ou com curl: volta a listagem do diretório /home/user. Uma porta que não é pública só responde a requisições que levam um token para ela: portas e previews.

Deixe-o pausar

Deixe o sandbox de lado por 5 minutos e ele pausa: a memória, os processos e o disco ficam guardados no servidor, por 30% do preço rodando. A próxima chamada, login SSH ou requisição à porta dele o acorda em cerca de 0,1 s, onde estava. Aqui ele é pausado na hora, e o servidor web continua lá depois de acordar:

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

Depois de 30 minutos ocioso, ele para: os processos terminam e o disco vai para o armazenamento de objetos, onde custa US$ 0,03 por GiB ao mês do que guarda. ResumeSandbox o inicia de novo. Ciclo de vida e ociosidade tem os timers e como alterá-los.

Exclua-o

DeleteSandbox descarta para sempre a memória e o disco do sandbox e responde com o registro final dele, com o que ele usou.

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

O mesmo pela CLI pethost

pethost sandbox, ou pethost sbx, faz cada um destes passos em um terminal, pelo SDK Go. O nome de um sandbox funciona onde quer que o id funcione.

Step 1: Entre

$ pethost login

O login é feito no seu navegador. Em um script, defina PETHOST_TOKEN em vez disso.

Step 2: Crie um 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

O id é impresso sozinho no stdout, então id=$(pethost sandbox new) o guarda.

Step 3: Rode um comando e copie arquivos para dentro

$ 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: Abra uma porta

$ 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: Pause-o e exclua-o

$ pethost sandbox pause api-dev
exdei47yr5je70v5   paused
$ pethost sandbox rm api-dev --yes
exdei47yr5je70v5   deleted

Com vários espaços de trabalho de sandboxes, nomeie um com -w. A referência da CLI tem todos os comandos.

O mesmo pelo seu agente

Um agente que fala MCP recebe sandboxes como ferramentas: adicione https://mcp.pethost.dev/sandboxes ao Claude Code, ao Codex, ao Cursor ou ao Claude, entre pelo navegador e peça a ele que rode algo em um sandbox. Conectar um agente tem os passos para cada um.

O que o cliente faz por você

Dois serviços respondem. O painel, em console.pethost.dev, guarda o registro de cada sandbox: criação, configurações, pausa, fork, exclusão. O servidor do próprio sandbox roda o que acontece dentro dele: comandos, arquivos, o desktop, links e agentes de código. Uma chamada do segundo tipo precisa do endereço desse servidor e de um token só para aquele sandbox. O cliente pega os dois da resposta de CreateSandbox ou ForkSandbox, ou os pede a ConnectSandbox, guarda-os até pouco antes de expirarem e pede de novo uma vez quando um servidor os recusa. O seu token de API nunca vai para o servidor de um sandbox.

Uma chamada que cria algo recebe um request_id. O cliente TypeScript dá um a cada chamada quando você o omite, e o mantém quando repete a chamada em uma nova conexão, para que o servidor a faça uma vez só. Envie o seu e envie-o de novo quando repetir depois de uma resposta perdida: a nova tentativa responde o que a primeira chamada fez, por 24 horas.

Em que espaço de trabalho uma chamada age

Uma chamada que nomeia um sandbox age no espaço de trabalho desse sandbox. Qualquer outra chamada age no espaço de trabalho que a requisição nomeia (workspace, por id ou nome), senão naquele com que o cliente foi criado, senão no seu único espaço de trabalho de sandboxes. Com um token que alcança vários, uma chamada que não nomeia nenhum é recusada com WorkspaceChoice, que os lista.

Quando não funciona

  • FAILED_PRECONDITION com WorkspaceChoice: o token alcança vários espaços de trabalho de sandboxes. Nomeie um: Sandboxes(workspace="..."), workspace na requisição, ou -w na CLI.
  • PERMISSION_DENIED em CreateSandbox: o token não recebeu acesso a este espaço de trabalho. Crie um em Conectar um agente ou seu código do próprio espaço de trabalho, ou dê o acesso em Configurações.
  • UNAUTHENTICATED: o token está ausente, digitado errado ou revogado. Confira o PETHOST_TOKEN no shell que roda o programa.
  • RESOURCE_EXHAUSTED com LimitReached, vcpus: os sandboxes do espaço de trabalho ocupam todas as vCPUs dele, tanto os rodando quanto os pausados. O teste grátis tem 4: um sandbox DEFAULT, ou dois SMALL. Exclua ou pare um, ou peça SMALL.
  • RESOURCE_EXHAUSTED com LimitReached, starts_per_minute, _hour ou _day: inícios demais nessa janela. Inícios são grátis e limitados: retry_time diz quando a chamada cabe. Limites tem os de cada plano.
  • O comando responde RUNNING: ele levou mais de 45 s e continua rodando. GetCommand com o command_id dele espera de novo.

Erros lista cada recusa e o que fazer.

Perguntas

Preciso de um SDK separado para sandboxes?

Não. O cliente de sandboxes faz parte do SDK do Pethost em Python, TypeScript, Go e Rust: instale o pethost e importe o módulo de sandboxes dele.

Onde consigo um token de API?

No painel, no seu espaço de trabalho de sandboxes: Conectar um agente ou seu código, depois Criar um token de API. Ele começa com pth_ e é mostrado uma vez.

Tem teste grátis?

Sim: 7 dias com US$ 1 de uso e 4 vCPUs, para o primeiro espaço de trabalho de sandboxes de uma conta nova. É preciso um cartão.

O que acontece se eu esquecer um sandbox?

Ele pausa depois de 5 minutos ocioso e para depois de 30, então custa só os dados guardados. Ele nunca é excluído a não ser que você o exclua ou defina delete_after_idle_seconds.

Posso chamar a API sem um SDK?

Sim. Os dois serviços falam Connect, gRPC e gRPC-Web: um POST de JSON para /pethost.sandboxes.v1.SandboxService/<Method> com o seu token funciona, e a referência da API tem todos os campos.

Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

Começar o teste grátis