Documentación de Agent Sandboxes · Primeros pasos
Guía rápida: tu primer sandbox
Tu primer sandbox en unos minutos: instala un SDK, crea un token de API, crea un sandbox, ejecuta un comando en él, escribe un archivo, abre un puerto a internet, deja que se pause y elimínalo. Cada paso es una llamada, en Python, TypeScript, Go o Rust, y después vienen los mismos pasos con la CLI pethost.
- Un paquete: el SDK que ya conoces de Pethost, con un cliente para sandboxes al lado:
pethost.sandboxes,pethost/sandboxes,github.com/pethost-dev/sdk/go/sandboxes,pethost::sandboxes. - Un token: un token de API en
PETHOST_TOKEN. El cliente encuentra solo el servidor de cada sandbox y su token. - Un id: cada llamada nombra su sandbox por
sandbox_id. - Nada que limpiar a mano: un sandbox que olvidas se pausa tras 5 minutos y se detiene tras 30.
Instala un SDK
El cliente de los sandboxes forma parte del SDK de Pethost en cada lenguaje, así que una instalación te da los dos. Python 3.10, Node 22 (o Bun, o Deno), Go 1.26 y Rust 1.88 o posteriores.
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
Crea un token de API
Step 1: Crea un espacio de trabajo de Agent Sandboxes
Inicia sesión en console.pethost.dev y crea un espacio de trabajo, eligiendo Agent Sandboxes. El primero de una cuenta nueva empieza con una prueba gratis: 7 días con 1 US$ de uso y 4 vCPU, con tarjeta.
Step 2: Crea un token para él
En el espacio de trabajo, abre Conectar un agente o tu código y pulsa Crear un token de API. El token empieza por pth_, solo llega a este espacio de trabajo y se muestra una vez. Tus tokens se listan, y se revocan, en los Ajustes de tu cuenta.
Step 3: Dáselo a tu programa
export PETHOST_TOKEN=pth_...
El cliente de Python y la CLI lo leen del entorno; los programas de abajo se lo pasan a los clientes de TypeScript, Go y Rust. Déjalo fuera de tu código: actúa como tu cuenta.
Crea un sandbox
Un sandbox se inicia desde una plantilla. La nuestra, base, es Ubuntu 24.04 con Python, Node.js, Docker, tres agentes de programación y Chrome. CreateSandbox responde una vez que el sandbox está en ejecución, en unos 0,15 s en el lado del servidor, más tu viaje de ida y vuelta al panel.
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": "…", …}}
Guarda el id: todas las demás llamadas nombran el sandbox por él. También puedes darle a un sandbox un name, único en el espacio de trabajo, por el que lo encuentra ListSandboxes.
Ejecuta un comando
RunCommand ejecuta un comando de shell como el usuario user en /home/user, y responde cuando termina, con su código de salida y los últimos 32 KiB de su salida. Un comando que tarda más de 45 s responde RUNNING y sigue: comandos y archivos dice cómo seguirlo.
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", …}
El comando fue al propio servidor del sandbox, no al panel. El SDK tomó la dirección del servidor y un token para este sandbox de la respuesta de la creación, y pide otros nuevos por su cuenta cuando caducan.
Escribe y lee un archivo
WriteFiles hace cambios en orden, en una llamada: escribe archivos enteros, edita uno por reemplazo exacto, mueve y elimina. Los paths son absolutos, o relativos a /home/user, y los directorios que faltan se crean.
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}");
}
Un cambio que falla detiene el lote, y la respuesta dice cuántos se hicieron y por qué falló el siguiente (failure): una edición cuyo old_text no está en el archivo, o está dos veces, no cambia nada.
Abre un puerto a internet
Inicia un servidor con wait_for_port: la llamada responde en cuanto algo escucha en el puerto, mientras el servidor sigue en ejecución. Después haz público el puerto. Recibe su propia dirección, https://<port>-<sandbox id>.<server>, que cualquiera puede 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}]}}}
Abre la dirección en un navegador, o con curl: vuelve el listado del directorio /home/user. Un puerto que no es público solo responde a las peticiones que llevan un token para él: puertos y previsualizaciones.
Deja que se pause
Deja el sandbox tranquilo 5 minutos y se pausa: su memoria, sus procesos y su disco se conservan en su servidor, al 30 % del precio en ejecución. La siguiente llamada, inicio de sesión SSH o petición a su puerto lo despierta en unos 0,1 s, donde estaba. Aquí se pausa al momento, y el servidor web sigue ahí tras despertar:
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": "…"}
Tras 30 minutos inactivo se detiene: sus procesos terminan, y su disco pasa al almacenamiento de objetos, donde cuesta 0,03 US$ por GiB al mes de lo que contiene. ResumeSandbox lo vuelve a iniciar. Ciclo de vida e inactividad tiene los temporizadores y cómo cambiarlos.
Elimínalo
DeleteSandbox borra para siempre la memoria y el disco del sandbox y responde su registro final, con lo que usó.
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": "…"}
Lo mismo desde la CLI pethost
pethost sandbox, o pethost sbx, hace cada uno de estos pasos desde una terminal, a través del SDK de Go. El nombre de un sandbox sirve allí donde sirve su id.
Step 1: Inicia sesión
$ pethost login
Inicia sesión en tu navegador. En un script, configura mejor PETHOST_TOKEN.
Step 2: Crea un 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
El id se imprime solo en stdout, así que id=$(pethost sandbox new) lo guarda.
Step 3: Ejecuta un comando, y copia archivos 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: Abre un puerto
$ 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: Páusalo, y elimínalo
$ pethost sandbox pause api-dev
exdei47yr5je70v5 paused
$ pethost sandbox rm api-dev --yes
exdei47yr5je70v5 deleted
Con varios espacios de trabajo de sandboxes, nombra uno con -w. La referencia de la CLI tiene todos los comandos.
Lo mismo desde tu agente
Un agente que habla MCP recibe los sandboxes como herramientas: agrega https://mcp.pethost.dev/sandboxes a Claude Code, Codex, Cursor o Claude, inicia sesión en tu navegador y pídele que ejecute algo en un sandbox. Conectar un agente tiene los pasos para cada uno.
Lo que el cliente hace por ti
Responden dos servicios. El panel, en console.pethost.dev, guarda el registro de cada sandbox: creación, ajustes, pausa, fork, eliminación. El propio servidor del sandbox ejecuta lo que pasa dentro de él: comandos, archivos, el escritorio, enlaces y agentes de programación. Una llamada del segundo tipo necesita la dirección de ese servidor y un token solo para ese sandbox. El cliente toma los dos de la respuesta de CreateSandbox o ForkSandbox, o se los pide a ConnectSandbox, los guarda hasta poco antes de que caduquen, y vuelve a pedirlos una vez cuando un servidor los rechaza. Tu token de API nunca va al servidor de un sandbox.
Una llamada que crea algo toma un request_id. El cliente de TypeScript le da uno a cada llamada cuando lo omites, y lo conserva cuando repite la llamada en una conexión nueva, para que el servidor la haga una sola vez. Envía el tuyo, y vuelve a enviarlo cuando reintentes tras una respuesta perdida: el reintento responde lo que hizo la primera llamada, durante 24 horas.
En qué espacio de trabajo actúa una llamada
Una llamada que nombra un sandbox actúa en el espacio de trabajo de ese sandbox. Cualquier otra llamada actúa en el espacio de trabajo que nombra su petición (workspace, por id o por nombre), si no en aquel con el que se creó el cliente, y si no en tu único espacio de trabajo de sandboxes. Si un token llega a varios y una llamada no nombra ninguno, se rechaza con WorkspaceChoice, que los lista.
Cuando no funciona
FAILED_PRECONDITIONconWorkspaceChoice: el token llega a varios espacios de trabajo de sandboxes. Nombra uno:Sandboxes(workspace="..."),workspaceen la petición, o-wen la CLI.PERMISSION_DENIEDenCreateSandbox: el token no tiene acceso a este espacio de trabajo. Crea uno en el propio Conectar un agente o tu código del espacio de trabajo, o dale acceso en Ajustes.UNAUTHENTICATED: el token falta, está mal escrito o se revocó. RevisaPETHOST_TOKENen la shell que ejecuta el programa.RESOURCE_EXHAUSTEDconLimitReached,vcpus: los sandboxes del espacio de trabajo ocupan todas sus vCPU, tanto los que están en ejecución como los que están en pausa. La prueba gratis tiene 4: un sandbox DEFAULT, o dos SMALL. Elimina o detén uno, o pideSMALL.RESOURCE_EXHAUSTEDconLimitReached,starts_per_minute,_houro_day: demasiados inicios en esa ventana. Los inicios son gratis, y limitados:retry_timedice cuándo cabe la llamada. Límites tiene los de cada plan.- El comando responde RUNNING: tardó más de 45 s y sigue en ejecución.
GetCommandcon sucommand_idvuelve a esperar.
Errores lista cada rechazo y qué hacer.
Preguntas
¿Necesito un SDK aparte para los sandboxes?
No. El cliente de los sandboxes forma parte del SDK de Pethost en Python, TypeScript, Go y Rust: instala pethost e importa su módulo de sandboxes.
¿Dónde consigo un token de API?
En el panel, en tu espacio de trabajo de sandboxes: Conectar un agente o tu código, y después Crear un token de API. Empieza por pth_ y se muestra una vez.
¿Hay una prueba gratis?
Sí: 7 días con 1 US$ de uso y 4 vCPU, para el primer espacio de trabajo de sandboxes de una cuenta nueva. Se pide una tarjeta.
¿Qué pasa si olvido un sandbox?
Se pausa tras 5 minutos inactivo y se detiene tras 30, así que solo cuesta sus datos guardados. Nunca se elimina salvo que lo elimines o configures delete_after_idle_seconds.
¿Puedo llamar a la API sin un SDK?
Sí. Los dos servicios hablan Connect, gRPC y gRPC-Web: funciona un POST de JSON a /pethost.sandboxes.v1.SandboxService/<Method> con tu token, y la referencia de la API tiene cada campo.
Prueba Pethost Agent Sandboxes
Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.