Docs do Agent Sandboxes · Tarefas
Rode comandos e edite arquivos em um sandbox
Rode um comando em um sandbox e receba a saída e o código de saída em uma chamada, acompanhe um comando longo enquanto ele roda, edite arquivos por substituição exata, mova arquivos de qualquer tamanho por links e abra um terminal no navegador.
RunCommandrodabash -lccomouserem/home/usere espera até 45 s: o código de saída e os últimos 32 KiB da saída, ou RUNNING com o id.WatchCommandtransmite a saída de um comando conforme ela chega;GetCommandespera de novo e lê só o que é novo.WriteFilesgrava, edita, move e exclui arquivos em uma chamada, em ordem; uma edição substitui um texto que aparece exatamente uma vez.- Links movem arquivos de qualquer tamanho e abrem um terminal no navegador.
Os exemplos continuam o início rápido: sandboxes (client em Go) é um cliente, e o id do sandbox está à mão.
Step 1: Rode um comando
Um comando é uma string, rodada por bash -lc, então pipes, && e variáveis funcionam. cwd e user mudam onde e como quem ele roda; user é root ou o padrão, user, que tem sudo sem senha.
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: Acompanhe um comando longo
Com wait_seconds 0, a chamada responde assim que o comando inicia. WatchCommand então envia a saída a partir dos últimos 64 KiB, conforme ela chega, e o comando como terminou por último.
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
Sem stream, GetCommand espera de novo até 45 s. Passe o stdout_bytes da última resposta que você leu como stdout_after_bytes, e ele envia só o que veio depois.
Step 3: Grave, edite e leia arquivos
WriteFiles recebe uma lista de alterações e as faz em ordem: text ou data grava um arquivo inteiro (com mode, senão 0644), edit substitui um trecho exato de um arquivo, move_to o move, delete exclui um arquivo ou um diretório, make_directory cria um. Diretórios que faltam são criados, e o lote para na primeira alteração que falha.
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: Mova um arquivo grande por um link
Uma chamada leva 1 MiB, WriteFiles 17 MiB e ReadFile 1 MiB. Um arquivo de qualquer tamanho passa por um link: CreateLink com download_path dá uma URL para um GET, e um diretório vem como .tar; com upload_path, uma URL para fazer PUT dos bytes do arquivo. Cada uma funciona uma vez e vai direto ao servidor do 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: Abra um terminal no navegador
CreateLink com terminal dá uma página com um shell no sandbox, para uma pessoa digitar; o command dele roda um programa no lugar do shell, como claude. Um WebSocket para a mesma URL leva os bytes do terminal nos dois sentidos, para um terminal seu.
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:~$
Um link expira depois de uma hora, a não ser que ttl_seconds diga outra coisa, 86.400 s no máximo, e leva um token na URL: entregue-o à pessoa que vai usá-lo, nunca a uma página que outros leem. Criar um não acorda nada.
Onde um comando roda
Um comando roda na VM do sandbox como user (uid 1000, sudo sem senha, no grupo docker) em /home/user, ou como root. O ambiente dele é o do template, com as variáveis do próprio sandbox por cima (settings.environment). stdin dá a ele uma entrada, que depois se fecha. Um comando roda até terminar, até timeout_seconds ou até StopCommand: a espera da chamada termina, o comando não.
Uma chamada a um sandbox pausado o acorda antes, em cerca de 80 ms. Um processo em segundo plano deixado rodando (um servidor iniciado com &) sobrevive às pausas, mas não mantém o sandbox acordado sozinho: inicie um job longo com keep_awake, para o timer de pausa esperar por ele (keep_awake).
Saída, offsets e histórico
Uma resposta traz os últimos 32 KiB do stdout e do stderr, em UTF-8, com output_truncated quando o começo foi cortado, e stdout_bytes e stderr_bytes, tudo o que foi escrito. exit_code é o do shell: 128 mais o número do sinal quando um sinal o encerrou, e ausente enquanto roda. O sandbox guarda os últimos 100 comandos encerrados para GetCommand. ListCommands lista os que rodam agora, iniciados pela API, por SSH ou em um terminal.
StopCommand envia SIGTERM, e SIGKILL 10 s depois se o comando ainda estiver rodando. Chamado para um comando que já terminou, ele mata o que esse comando deixou rodando em segundo plano.
Edições por substituição exata
Um edit substitui old_text por new_text onde old_text aparece exatamente uma vez no arquivo, de no máximo 16 MiB. Ausente é EDIT_NOT_FOUND; presente duas vezes ou mais é EDIT_AMBIGUOUS, e o arquivo fica igual nos dois casos. É a edição que os agentes de código fazem, e ela falha de forma clara onde um número de linha já estaria desatualizado. Uma gravação substitui um arquivo inteiro e mantém o dono e o modo dele; ela grava através de um link simbólico no destino dele.
WatchFiles transmite o que é criado, gravado, removido e renomeado em um diretório, com recursive para o que está abaixo dele. OVERFLOW diz que eventos se perderam: liste o diretório de novo.
Docker em um sandbox
Todo sandbox do base tem Docker, com Compose e Buildx. O daemon dele inicia na primeira conexão a /var/run/docker.sock e não custa nada até lá. Imagens e containers ficam no disco do sandbox, então uma parada os guarda e um template os leva. Pulls do Docker Hub passam primeiro por um mirror.
Quando não funciona
- A resposta é RUNNING, sem código de saída: o comando levou mais que
wait_secondse continua rodando. Acompanhe-o comWatchCommand, ou espere comGetCommand. - O sandbox pausou no meio de um build longo: nada o chamou enquanto o build rodava. Inicie esse trabalho com
keep_awakee umtimeout_seconds. failureéEDIT_NOT_FOUNDouEDIT_AMBIGUOUS: leia o arquivo de novo e envie umold_textque apareça uma vez; as alterações anteriores do lote foram feitas (done_count).RESOURCE_EXHAUSTEDsemLimitReached: a requisição passou do limite (um arquivo acima de 17 MiB: use um link de upload), ou o sandbox já atende 64 chamadas ao mesmo tempo. Encerre uma, ou espere.FAILED_PRECONDITIONcomStopped: o sandbox está parado.ResumeSandboxo inicia, com os arquivos como ele os deixou.- Um comando que estava RUNNING está
LOST: o sandbox perdeu a memória (parou) enquanto o comando rodava. Rode-o de novo.
Perguntas
Por quanto tempo um comando pode rodar?
Pelo tempo que precisar: a chamada espera até 45 s e o comando continua rodando. Só timeout_seconds ou StopCommand o encerram antes.
Posso rodar comandos como root?
Sim: user root, ou sudo, que user tem sem senha.
Como envio um arquivo grande para um sandbox?
CreateLink com upload_path dá uma URL para fazer PUT do arquivo, de qualquer tamanho, ou pethost sandbox cp faz isso por você.
Posso rodar Docker dentro de um sandbox?
Sim. Docker, Compose e Buildx estão no base, e o daemon inicia no primeiro uso.
Um processo em segundo plano rodando mantém o sandbox acordado?
Não. Ele sobrevive às pausas, e uma requisição à porta dele acorda o sandbox, mas só chamadas, sessões e comandos keep_awake o impedem de pausar.
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.