Docs do Agent Sandboxes · Começar
Início rápido: o seu primeiro sandbox
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.
- 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.
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
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.
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": "…", …}}
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.
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", …}
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.
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}");
}
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.
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}]}}}
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:
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": "…"}
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.
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": "…"}
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_PRECONDITIONcomWorkspaceChoice: o token alcança vários espaços de trabalho de sandboxes. Nomeie um:Sandboxes(workspace="..."),workspacena requisição, ou-wna CLI.PERMISSION_DENIEDemCreateSandbox: 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 oPETHOST_TOKENno shell que roda o programa.RESOURCE_EXHAUSTEDcomLimitReached,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çaSMALL.RESOURCE_EXHAUSTEDcomLimitReached,starts_per_minute,_hourou_day: inícios demais nessa janela. Inícios são grátis e limitados:retry_timediz quando a chamada cabe. Limites tem os de cada plano.- O comando responde RUNNING: ele levou mais de 45 s e continua rodando.
GetCommandcom ocommand_iddele 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.