Español
Menú de la documentación

Documentación de Agent Sandboxes · Tareas

Ejecuta comandos y edita archivos en un sandbox

Actualizado · 9 min de lectura

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.

En resumen
  • RunCommand ejecuta bash -lc como user en /home/user y espera hasta 45 s: su código de salida y los últimos 32 KiB de su salida, o RUNNING con su id.
  • WatchCommand transmite la salida de un comando a medida que llega; GetCommand vuelve a esperar y solo lee lo nuevo.
  • WriteFiles escribe, 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.

Python
command = sandboxes.run_command(sandbox_id, command="uname -r && whoami", cwd="/tmp")
print(command.exit_code)
print(command.stdout)
# 0
# 6.18.63
# user
TypeScript
const command = await sandboxes.runCommand({ sandboxId, command: "uname -r && whoami", cwd: "/tmp" });
console.log(command.exitCode);
console.log(command.stdout);
Go
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)
Rust
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);
CLI
$ 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.

Python
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
TypeScript
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);
}
Go
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)
	}
}
Rust
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),
        _ => {}
    }
}
CLI
$ 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.

Python
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
TypeScript
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);
Go
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)
}
Rust
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.

Python
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…
TypeScript
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);
Go
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)
Rust
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);
CLI
$ 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.

Python
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…
TypeScript
const terminal = await sandboxes.createLink({ sandboxId, terminal: {}, ttlSeconds: 900 });
console.log(terminal.url);
Go
terminal, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{
	SandboxID:  id,
	Target:     sandboxes.CreateLinkTerminal{},
	TTLSeconds: 900,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(terminal.URL)
Rust
let terminal = sandboxes
    .create_link(CreateLinkRequest {
        sandbox_id: id.clone(),
        target: Some(CreateLinkRequestTarget::Terminal(TerminalLink::default())),
        ttl_seconds: 900,
    })
    .await?;
println!("{}", terminal.url);
CLI
$ 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_seconds y sigue en ejecución. Síguelo con WatchCommand, o espera con GetCommand.
  • El sandbox se pausó a mitad de un build largo: nada lo llamó mientras se ejecutaba el build. Inicia ese trabajo con keep_awake y un timeout_seconds.
  • failure es EDIT_NOT_FOUND o EDIT_AMBIGUOUS: vuelve a leer el archivo y envía un old_text que aparezca una vez; los cambios anteriores del lote sí se hicieron (done_count).
  • RESOURCE_EXHAUSTED sin LimitReached: 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_PRECONDITION con Stopped: el sandbox está detenido. ResumeSandbox lo 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.

Empezar la prueba gratis