English
Get started

Agent Sandboxes Commands, files and a terminal

A code execution sandbox for AI agents

Your model writes code, a sandbox runs it, and the output comes back in the same call. Commands, files and terminals are one API, answered by the server the sandbox runs on, not by the panel.

Code execution in one call

Every sandbox is a Firecracker microVM with its own Linux kernel and root inside, started from our base template in about 0.15 s: Ubuntu 24.04 with build tools, Python 3, Node.js 22 and Docker. run_command runs a command through bash -lc as user, who has sudo, or as root, in any directory you name. The call waits up to 45 seconds for the command to end and answers its exit code and the last 32 KiB of its stdout and stderr.

Three fields change what the call waits for:

  • wait_for_port answers as soon as something listens on a port, while the command runs on: npm run dev and 5173.
  • wait_seconds=0 answers once the command has started. get_command waits for it again, and watch_command streams its output, the last 64 KiB first, then live.
  • timeout_seconds ends a command that runs too long. Without it, only stop_command ends one: SIGTERM, then SIGKILL 10 s later.

Each answer says how many bytes the command has written; pass them back and the next answer holds only what is new. With a request_id, a retry within 24 hours runs nothing again and answers what the first call did. list_commands shows what runs now, commands typed over SSH included, and the last 100 that ended are kept.

from pethost.sandboxes import FileChange, Sandboxes, TextEdit

sandboxes = Sandboxes()  # reads PETHOST_TOKEN
box = sandboxes.create_sandbox()
code = "x = 1\nprint(x * 42)\n"
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", text=code)])
out = sandboxes.run_command(box.sandbox_id, command="python3 app.py", timeout_seconds=30)
print(out.exit_code, out.stdout)  # 0 42

edit = TextEdit(old_text="x = 1", new_text="x = 2")
sandboxes.write_files(box.sandbox_id, changes=[FileChange(path="app.py", edit=edit)])
server = sandboxes.run_command(box.sandbox_id, command="python3 -m http.server 8000",
                               wait_for_port=8000)
print(server.state.name)  # RUNNING: it answered once port 8000 listened
pethost sandbox new --name tests --size small
pethost sandbox cp ./app tests:/home/user/app
pethost sandbox run tests --cwd /home/user/app -- python3 -m unittest
pethost sandbox open tests --terminal

Files: batches and exact edits

write_files takes a list of changes and makes them in order: write a file’s text or bytes, replace text that occurs exactly once in it, move, delete, make a directory, set a mode. Missing parent directories are made. It stops at the first change that fails and says which, with a reason to branch on, such as the text to replace not being there. So an edit lands only where its text is. A request carries up to 17 MiB.

read_file reads up to 1 MiB from any offset, list_files lists a directory as deep as you ask, and watch_files streams every change under one. A file of any size moves through a link from create_link: a download URL sends the file, or a directory as a .tar; an upload URL takes a PUT. Each works once.

A terminal in the browser

create_link with a terminal gives a page that runs bash, or a command such as claude, and a WebSocket at the same URL that carries its bytes, for a terminal inside your own product. A link lasts an hour by default and a day at most.

What runs inside

Docker runs in every sandbox: dockerd starts at the first connection to its socket and keeps images on the sandbox’s disk, so they survive a stop and a template carries them. The rest comes from apt, with sudo.

Calls go straight to the sandbox’s server, which the SDK finds for you. The first command after a create answers in 29 to 48 ms. On a server running 74 sandboxes, each building a JavaScript project and waiting between builds as an agent does, a trivial command took 6 ms (28 ms at the 95th percentile).

Limits and prices

WhatLimit
Calls at once, per sandbox64; a write_files counts as 16
A request1 MiB; write_files 17 MiB
An answerabout 64 KiB; read_file 1 MiB; any size through a link
Output in an answerthe last 32 KiB of stdout and of stderr

Commands, files and links have no price of their own: you pay for the sandbox’s running seconds, from $0.018 an hour for SMALL (2 vCPU, 4 GiB) to $0.144 for XLARGE (16 vCPU, 32 GiB), each run rounded up to a second and 10 s at least. Idle for 5 minutes, it pauses at 30% of that. How billing by the second works.

How it compares

On 21 November 2026, E2B charged $0.1656 an hour for a sandbox of 2 vCPU and 4 GiB, and so did Daytona; Pethost’s SMALL, the same size, costs $0.018. E2B’s sessions lasted up to 1 hour on its Hobby plan and 24 hours on Pro, Vercel Sandbox’s 45 minutes on Hobby and 24 hours on Pro. A Pethost sandbox has no limit on how long it lives.

Read the docs

Questions

Which languages can a code execution sandbox run?

Anything that runs on Linux. Python 3 and Node.js 22 are installed, Docker runs, and apt installs the rest. Save a sandbox with your tools as a template and new sandboxes start with them.

How long can a command run?

As long as it needs: one call waits up to 45 seconds, then you read or stream its output. Idle for 5 minutes, a sandbox pauses with the command in memory, which goes on at the next call. A command started with keep_awake runs straight through, and so does one you follow with watch_command.

Can the code reach the internet?

Yes, over TCP: by default a sandbox may connect anywhere. An egress allow-list narrows that to the domains, IPs and ports you name. No UDP leaves a sandbox.

How do I move large files?

Through a download or upload link, any size, or with scp over SSH.

Related

Give your agent a computer in 0.15 s

Start the free trial