Português
Menu da documentação

Docs do Agent Sandboxes · Tarefas

Rode comandos e edite arquivos em um sandbox

Atualizado em · 9 min de leitura

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.

Em resumo
  • RunCommand roda bash -lc como user em /home/user e espera até 45 s: o código de saída e os últimos 32 KiB da saída, ou RUNNING com o id.
  • WatchCommand transmite a saída de um comando conforme ela chega; GetCommand espera de novo e lê só o que é novo.
  • WriteFiles grava, 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.

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: 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.

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

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.

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: 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.

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: 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.

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:~$

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_seconds e continua rodando. Acompanhe-o com WatchCommand, ou espere com GetCommand.
  • O sandbox pausou no meio de um build longo: nada o chamou enquanto o build rodava. Inicie esse trabalho com keep_awake e um timeout_seconds.
  • failure é EDIT_NOT_FOUND ou EDIT_AMBIGUOUS: leia o arquivo de novo e envie um old_text que apareça uma vez; as alterações anteriores do lote foram feitas (done_count).
  • RESOURCE_EXHAUSTED sem LimitReached: 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_PRECONDITION com Stopped: o sandbox está parado. ResumeSandbox o 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.

Começar o teste grátis