Documentación de Agent Sandboxes · Tareas
Ejecuta comandos y edita archivos en un sandbox
Ejecuta un comando en un sandbox y recibe su salida y su código de salida en una llamada, sigue uno largo mientras se ejecuta, edita archivos por reemplazo exacto, mueve archivos de cualquier tamaño a través de enlaces y abre una terminal en un navegador.
RunCommandejecutabash -lccomouseren/home/usery espera hasta 45 s: su código de salida y los últimos 32 KiB de su salida, o RUNNING con su id.WatchCommandtransmite la salida de un comando a medida que llega;GetCommandvuelve a esperar y solo lee lo nuevo.WriteFilesescribe, edita, mueve y elimina archivos en una llamada, en orden; una edición reemplaza un texto que aparece exactamente una vez.- Los enlaces mueven archivos de cualquier tamaño y abren una terminal en un navegador.
Los ejemplos siguen desde la guía rápida: sandboxes (client en Go) es un cliente, y tienes a mano el id del sandbox.
Step 1: Ejecuta un comando
Un comando es un string que ejecuta bash -lc, así que funcionan las tuberías, && y las variables. cwd y user cambian dónde y como quién se ejecuta; user es root o el valor por defecto, user, que tiene sudo sin contraseña.
command = sandboxes.run_command(sandbox_id, command="uname -r && whoami", cwd="/tmp")
print(command.exit_code)
print(command.stdout)
# 0
# 6.18.63
# user
const command = await sandboxes.runCommand({ sandboxId, command: "uname -r && whoami", cwd: "/tmp" });
console.log(command.exitCode);
console.log(command.stdout);
command, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: "uname -r && whoami", Cwd: "/tmp"})
if err != nil {
log.Fatal(err)
}
fmt.Println(*command.ExitCode)
fmt.Println(command.Stdout)
let command = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "uname -r && whoami".into(),
cwd: "/tmp".into(),
..Default::default()
})
.await?;
println!("{:?}", command.exit_code);
println!("{}", command.stdout);
$ pethost sandbox run api-dev --cwd /tmp -- 'uname -r && whoami'
6.18.63
user
Step 2: Sigue un comando largo
Con wait_seconds a 0, la llamada responde en cuanto se inicia el comando. WatchCommand envía entonces su salida desde los últimos 64 KiB en adelante, a medida que llega, y el comando tal como terminó al final.
import sys
job = sandboxes.run_command(
sandbox_id,
command="for i in 1 2 3; do echo step $i; sleep 20; done",
wait_seconds=0,
timeout_seconds=600,
)
for out in sandboxes.watch_command(sandbox_id, command_id=job.command_id):
if out.stdout is not None:
sys.stdout.write(out.stdout.decode())
if out.ended is not None:
print("exit", out.ended.exit_code)
# step 1
# step 2
# step 3
# exit 0
const job = await sandboxes.runCommand({
sandboxId,
command: "for i in 1 2 3; do echo step $i; sleep 20; done",
waitSeconds: 0,
timeoutSeconds: 600,
});
for await (const out of sandboxes.watchCommand({ sandboxId, commandId: job.commandId })) {
if (out.output === "stdout") process.stdout.write(out.stdout);
if (out.output === "ended") console.log("exit", out.ended.exitCode);
}
job, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
SandboxID: id,
Command: "for i in 1 2 3; do echo step $i; sleep 20; done",
WaitSeconds: new(uint32(0)),
TimeoutSeconds: 600,
})
if err != nil {
log.Fatal(err)
}
for out, err := range client.WatchCommand(ctx, &sandboxes.WatchCommandRequest{SandboxID: id, CommandID: job.CommandID}) {
if err != nil {
log.Fatal(err)
}
switch output := out.Output.(type) {
case sandboxes.CommandOutputStdout:
os.Stdout.Write(output)
case sandboxes.CommandOutputEnded:
fmt.Println("exit", *output.ExitCode)
}
}
let job = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "for i in 1 2 3; do echo step $i; sleep 20; done".into(),
wait_seconds: Some(0),
timeout_seconds: 600,
..Default::default()
})
.await?;
let mut output = sandboxes.watch_command(WatchCommandRequest {
sandbox_id: id.clone(),
command_id: job.command_id,
});
while let Some(out) = output.next().await {
match out?.output {
Some(CommandOutputOutput::Stdout(bytes)) => print!("{}", String::from_utf8_lossy(&bytes)),
Some(CommandOutputOutput::Ended(ended)) => println!("exit {:?}", ended.exit_code),
_ => {}
}
}
$ pethost sandbox run api-dev --timeout 10m -- 'for i in 1 2 3; do echo step $i; sleep 20; done'
step 1
step 2
step 3
Sin stream, GetCommand vuelve a esperar hasta 45 s. Pasa el stdout_bytes de la última respuesta que leíste como stdout_after_bytes, y solo enviará lo que llegó después.
Step 3: Escribe, edita y lee archivos
WriteFiles toma una lista de cambios y los hace en orden: text o data escribe un archivo entero (con mode, si no 0644), edit reemplaza un fragmento exacto de un archivo, move_to lo mueve, delete elimina un archivo o un directorio, make_directory crea uno. Los directorios que faltan se crean, y el lote se detiene en el primer cambio que falla.
from pethost.sandboxes import FileChange, TextEdit
done = sandboxes.write_files(sandbox_id, changes=[
FileChange(path="app/run.sh", text="#!/bin/sh\necho ready\n", mode="0755"),
FileChange(path="app/run.sh", edit=TextEdit(old_text="ready", new_text="ready to go")),
])
print(done.done_count, done.failure.name)
for entry in sandboxes.list_files(sandbox_id, path="app").files:
print(entry.path, entry.mode, entry.size_bytes)
print(sandboxes.read_file(sandbox_id, path="app/run.sh").text)
# 2 UNSPECIFIED
# /home/user/app/run.sh 0755 27
# #!/bin/sh
# echo ready to go
const done = await sandboxes.writeFiles({
sandboxId,
changes: [
{ path: "app/run.sh", text: "#!/bin/sh\necho ready\n", mode: "0755" },
{ path: "app/run.sh", edit: { oldText: "ready", newText: "ready to go" } },
],
});
console.log(done.doneCount, done.failure);
const { files } = await sandboxes.listFiles({ sandboxId, path: "app" });
for (const entry of files) console.log(entry.path, entry.mode, entry.sizeBytes);
console.log((await sandboxes.readFile({ sandboxId, path: "app/run.sh" })).text);
done, err := client.WriteFiles(ctx, &sandboxes.WriteFilesRequest{SandboxID: id, Changes: []sandboxes.FileChange{
{Path: "app/run.sh", Change: sandboxes.FileChangeText("#!/bin/sh\necho ready\n"), Mode: "0755"},
{Path: "app/run.sh", Change: sandboxes.FileChangeEdit{OldText: "ready", NewText: "ready to go"}},
}})
if err != nil {
log.Fatal(err)
}
fmt.Println(done.DoneCount, done.Failure)
list, err := client.ListFiles(ctx, &sandboxes.ListFilesRequest{SandboxID: id, Path: "app"})
if err != nil {
log.Fatal(err)
}
for _, entry := range list.Files {
fmt.Println(entry.Path, entry.Mode, entry.SizeBytes)
}
let script = |change| FileChange { path: "app/run.sh".into(), change: Some(change), ..Default::default() };
let done = sandboxes
.write_files(WriteFilesRequest {
sandbox_id: id.clone(),
changes: vec![
FileChange { mode: "0755".into(), ..script(FileChangeChange::Text("#!/bin/sh\necho ready\n".into())) },
script(FileChangeChange::Edit(TextEdit { old_text: "ready".into(), new_text: "ready to go".into() })),
],
})
.await?;
println!("{} {:?}", done.done_count, done.failure);
let list = sandboxes
.list_files(ListFilesRequest { sandbox_id: id.clone(), path: "app".into(), ..Default::default() })
.await?;
for entry in list.files {
println!("{} {} {}", entry.path, entry.mode, entry.size_bytes);
}
Step 4: Mueve un archivo grande a través de un enlace
Una llamada lleva 1 MiB, WriteFiles 17 MiB y ReadFile 1 MiB. Un archivo de cualquier tamaño se mueve mejor a través de un enlace: CreateLink con download_path da una URL para hacer GET, y un directorio llega como .tar; con upload_path, una URL a la que hacer PUT de los bytes del archivo. Cada una funciona una vez, y va directa al servidor del sandbox.
upload = sandboxes.create_link(sandbox_id, upload_path="data/train.csv")
results = sandboxes.create_link(sandbox_id, download_path="results")
print(upload.url)
print(results.url)
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
const upload = await sandboxes.createLink({ sandboxId, uploadPath: "data/train.csv" });
const results = await sandboxes.createLink({ sandboxId, downloadPath: "results" });
console.log(upload.url);
console.log(results.url);
upload, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{SandboxID: id, Target: sandboxes.CreateLinkUploadPath("data/train.csv")})
if err != nil {
log.Fatal(err)
}
results, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{SandboxID: id, Target: sandboxes.CreateLinkDownloadPath("results")})
if err != nil {
log.Fatal(err)
}
fmt.Println(upload.URL)
fmt.Println(results.URL)
let link = |target| CreateLinkRequest { sandbox_id: id.clone(), target: Some(target), ..Default::default() };
let upload = sandboxes.create_link(link(CreateLinkRequestTarget::UploadPath("data/train.csv".into()))).await?;
let results = sandboxes.create_link(link(CreateLinkRequestTarget::DownloadPath("results".into()))).await?;
println!("{}", upload.url);
println!("{}", results.url);
$ pethost sandbox cp ./data/train.csv api-dev:data/train.csv
✓ Copied ./data/train.csv to zt01ocz93yiwpy31:data/train.csv · 22 KB in <1 s
$ pethost sandbox cp api-dev:results ./results
✓ Copied zt01ocz93yiwpy31:results to ./results · 4 KB in <1 s
curl -T train.csv "$UPLOAD_URL"
curl -o results.tar "$RESULTS_URL"
Step 5: Abre una terminal en un navegador
CreateLink con terminal da una página con una shell en el sandbox, para que una persona escriba en ella; su command ejecuta un programa en lugar de la shell, como claude. Un WebSocket a la misma URL lleva los bytes de la terminal en los dos sentidos, para una terminal propia.
from pethost.sandboxes import TerminalLink
print(sandboxes.create_link(sandbox_id, terminal=TerminalLink(), ttl_seconds=900).url)
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
const terminal = await sandboxes.createLink({ sandboxId, terminal: {}, ttlSeconds: 900 });
console.log(terminal.url);
terminal, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{
SandboxID: id,
Target: sandboxes.CreateLinkTerminal{},
TTLSeconds: 900,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(terminal.URL)
let terminal = sandboxes
.create_link(CreateLinkRequest {
sandbox_id: id.clone(),
target: Some(CreateLinkRequestTarget::Terminal(TerminalLink::default())),
ttl_seconds: 900,
})
.await?;
println!("{}", terminal.url);
$ pethost sandbox open api-dev --terminal
✓ Opened the terminal of e9bprbw1hovj6sw5 in your browser.
$ pethost sandbox shell api-dev
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.
user@e9bprbw1hovj6sw5:~$
Un enlace caduca tras una hora salvo que ttl_seconds diga otra cosa, 86.400 s como máximo, y lleva un token en su URL: dáselo a la persona que lo usará, nunca a una página que lean otros. Crear uno no despierta nada.
Dónde se ejecuta un comando
Un comando se ejecuta en la VM del sandbox como user (uid 1000, sudo sin contraseña, en el grupo docker) en /home/user, o como root. Su entorno es el de la plantilla, con las variables propias del sandbox por encima (settings.environment). stdin le da una entrada, que después se cierra. Un comando se ejecuta hasta que termina, hasta timeout_seconds o hasta StopCommand: lo que termina es la espera de la llamada, no el comando.
Una llamada a un sandbox en pausa lo despierta primero, en unos 80 ms. Un proceso que queda en segundo plano (un servidor iniciado con &) sobrevive a las pausas, pero no mantiene despierto el sandbox por sí solo: inicia un trabajo largo con keep_awake, para que el temporizador de pausa lo espere (keep_awake).
Salida, offsets e historial
Una respuesta trae los últimos 32 KiB de stdout y de stderr, en UTF-8, con output_truncated cuando se cortó el principio, y stdout_bytes y stderr_bytes, todo lo que se escribió. exit_code es el de la shell: 128 más el número de la señal cuando lo terminó una señal, y no aparece mientras se ejecuta. El sandbox guarda sus últimos 100 comandos terminados para GetCommand. ListCommands lista los que se ejecutan ahora, iniciados por la API, por SSH o en una terminal.
StopCommand envía SIGTERM, y SIGKILL 10 s después si el comando sigue en ejecución. Si se llama para un comando que ya terminó, mata lo que ese comando dejó ejecutándose en segundo plano.
Ediciones por reemplazo exacto
Un edit reemplaza old_text por new_text donde old_text aparece exactamente una vez en el archivo, de 16 MiB como máximo. Si no está, es EDIT_NOT_FOUND; si está dos veces o más, EDIT_AMBIGUOUS, y en los dos casos el archivo no cambia. Es la edición que hacen los agentes de programación, y falla de forma visible donde un número de línea se habría quedado desfasado. Una escritura reemplaza un archivo entero y conserva su propietario y su modo; escribe a través de un enlace simbólico en su destino.
WatchFiles transmite lo que se crea, se escribe, se elimina y se renombra en un directorio, con recursive para lo que hay por debajo. OVERFLOW dice que se perdieron eventos: vuelve a listar el directorio.
Docker en un sandbox
Todos los sandboxes desde base tienen Docker, con Compose y Buildx. Su daemon se inicia con la primera conexión a /var/run/docker.sock y no cuesta nada hasta entonces. Las imágenes y los contenedores están en el disco del sandbox, así que una detención los conserva y una plantilla los lleva. Las descargas desde Docker Hub pasan primero por un mirror.
Cuando no funciona
- La respuesta es RUNNING, sin código de salida: el comando tardó más que
wait_secondsy sigue en ejecución. Síguelo conWatchCommand, o espera conGetCommand. - El sandbox se pausó a mitad de un build largo: nada lo llamó mientras se ejecutaba el build. Inicia ese trabajo con
keep_awakey untimeout_seconds. failureesEDIT_NOT_FOUNDoEDIT_AMBIGUOUS: vuelve a leer el archivo y envía unold_textque aparezca una vez; los cambios anteriores del lote sí se hicieron (done_count).RESOURCE_EXHAUSTEDsinLimitReached: la petición pasó de su límite (un archivo de más de 17 MiB: usa un enlace de subida), o el sandbox ya atiende 64 llamadas a la vez. Termina una, o espera.FAILED_PRECONDITIONconStopped: el sandbox está detenido.ResumeSandboxlo inicia, con sus archivos como los dejó.- Un comando que estaba RUNNING pasa a
LOST: el sandbox perdió su memoria (se detuvo) mientras el comando se ejecutaba. Ejecútalo otra vez.
Preguntas
¿Cuánto tiempo puede ejecutarse un comando?
El que necesite: la llamada espera hasta 45 s y el comando sigue. Solo timeout_seconds o StopCommand lo terminan antes.
¿Puedo ejecutar comandos como root?
Sí: user root, o sudo, que user tiene sin contraseña.
¿Cómo subo un archivo grande a un sandbox?
CreateLink con upload_path da una URL a la que hacer PUT del archivo, de cualquier tamaño, o pethost sandbox cp lo hace por ti.
¿Puedo ejecutar Docker dentro de un sandbox?
Sí. Docker, Compose y Buildx están en base, y el daemon se inicia con el primer uso.
¿Un proceso en segundo plano mantiene despierto el sandbox?
No. Sobrevive a las pausas, y una petición a su puerto despierta el sandbox, pero solo las llamadas, las sesiones y los comandos keep_awake evitan que se pause.
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.