Agent Sandboxes docs · Tasks
Run commands and edit files in a sandbox
Run a command in a sandbox and get its output and exit code in one call, follow a long one as it runs, edit files by exact replacement, move files of any size through links, and open a terminal in a browser.
RunCommandrunsbash -lcasuserin/home/userand waits up to 45 s: its exit code and the last 32 KiB of its output, or RUNNING with its id.WatchCommandstreams a command's output as it comes;GetCommandwaits again and reads only what is new.WriteFileswrites, edits, moves and deletes files in one call, in order; an edit replaces text that occurs exactly once.- Links move files of any size and open a terminal in a browser.
The examples go on from the quickstart: sandboxes (client in Go) is a client, and the sandbox's id is at hand.
Step 1: Run a command
A command is one string, run by bash -lc, so pipes, && and variables work. cwd and user change where and as whom it runs; user is root or the default, user, who has passwordless sudo.
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: Follow a long command
With wait_seconds 0 the call answers as soon as the command has started. WatchCommand then sends its output from the last 64 KiB on, as it comes, and the command as it ended last.
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
Without a stream, GetCommand waits up to 45 s again. Pass the stdout_bytes of the answer you last read as stdout_after_bytes, and it sends only what came after.
Step 3: Write, edit and read files
WriteFiles takes a list of changes and makes them in order: text or data writes a file whole (with mode, else 0644), edit replaces one exact piece of a file, move_to moves it, delete deletes a file or a directory, make_directory makes one. Missing directories are made, and the batch stops at the first change that fails.
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: Move a large file through a link
A call carries 1 MiB, WriteFiles 17 MiB and ReadFile 1 MiB. A file of any size moves through a link instead: CreateLink with download_path gives a URL to GET, a directory coming as a .tar; with upload_path, a URL to PUT the file's bytes to. Each works once, and goes straight to the sandbox's server.
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: Open a terminal in a browser
CreateLink with terminal gives a page with a shell in the sandbox, for a person to type in; its command runs a program in place of the shell, as claude. A WebSocket to the same URL carries the terminal's bytes both ways, for a terminal of your own.
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:~$
A link expires after an hour unless ttl_seconds says otherwise, 86,400 s at most, and holds a token in its URL: give it to the person who will use it, never to a page others read. Making one wakes nothing.
Where a command runs
A command runs in the sandbox's VM as user (uid 1000, passwordless sudo, in the docker group) in /home/user, or as root. Its environment is the template's, with the sandbox's own variables over it (settings.environment). stdin gives it input, which then closes. A command runs until it ends, until timeout_seconds, or until StopCommand: the call's wait ends, the command does not.
A call into a paused sandbox wakes it first, in about 80 ms. A background process left running (a server started with &) lives on through pauses, but does not keep the sandbox awake by itself: start a long job with keep_awake, so the pause timer waits for it (keep_awake).
Output, offsets and history
An answer holds the last 32 KiB of stdout and of stderr, as UTF-8, with output_truncated when the beginning was cut, and stdout_bytes and stderr_bytes, all that was written. exit_code is the shell's: 128 plus the signal's number when a signal ended it, and absent while it runs. The sandbox keeps its last 100 ended commands for GetCommand. ListCommands lists those running now, started by the API, over SSH or in a terminal.
StopCommand sends SIGTERM, and SIGKILL 10 s later if the command still runs. Called for a command that has ended, it kills what that command left running in the background.
Edits by exact replacement
An edit replaces old_text with new_text where old_text occurs exactly once in the file, of 16 MiB at most. Not there is EDIT_NOT_FOUND; there twice or more is EDIT_AMBIGUOUS, and the file is unchanged either way. It is the edit coding agents make, and it fails loudly where a line number would have gone stale. A write replaces a file whole and keeps its owner and mode; it writes through a symbolic link to its target.
WatchFiles streams what is created, written, removed and renamed under a directory, with recursive for those under it. OVERFLOW says events were lost: list the directory again.
Docker in a sandbox
Every sandbox from base has Docker, with Compose and Buildx. Its daemon starts at the first connection to /var/run/docker.sock and costs nothing until then. Images and containers are on the sandbox's disk, so a stop keeps them and a template carries them. Pulls from Docker Hub go through a mirror first.
When it does not work
- The answer is RUNNING, with no exit code: the command took longer than
wait_secondsand runs on. Follow it withWatchCommand, or wait withGetCommand. - The sandbox paused under a long build: nothing called it while the build ran. Start such work with
keep_awakeand atimeout_seconds. failureisEDIT_NOT_FOUNDorEDIT_AMBIGUOUS: read the file again and send anold_textthat occurs once; the changes before it in the batch were made (done_count).RESOURCE_EXHAUSTEDwithoutLimitReached: the request was over its bound (a file over 17 MiB: use an upload link), or the sandbox serves 64 calls at once already. End one, or wait.FAILED_PRECONDITIONwithStopped: the sandbox is stopped.ResumeSandboxstarts it, its files as it left them.- A command that was RUNNING is
LOST: the sandbox lost its memory (it stopped) while the command ran. Run it again.
Questions
How long can a command run?
As long as it needs: the call waits up to 45 s and the command runs on. Only timeout_seconds or StopCommand ends it early.
Can I run commands as root?
Yes: user root, or sudo, which user has without a password.
How do I upload a large file to a sandbox?
CreateLink with upload_path gives a URL to PUT the file to, of any size, or pethost sandbox cp does it for you.
Can I run Docker inside a sandbox?
Yes. Docker, Compose and Buildx are in base, and the daemon starts at first use.
Does a running background process keep the sandbox awake?
No. It survives pauses, and a request to its port wakes the sandbox, but only calls, sessions and keep_awake commands keep it from pausing.
Try Pethost Agent Sandboxes
A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.