Pethost Agent Sandboxes docs
A sandbox is a Linux microVM for code, coding agents and a desktop with Chrome: a Firecracker VM with its own kernel, and root inside. It starts from a template in about 0.15 s, pauses with its memory and processes when nothing happens in it, wakes at the next call in about 0.1 s, and stops to object storage when it stays idle longer. You pay by the second for what each state holds.
In its server's memory
Runs your processes and answers every call.
$0.018 an hour, SMALL
Idle 5 min: it pauses
The next call wakes it
On its server's disk
Keeps memory, processes and disk.
$0.0054 an hour, SMALL
Idle 30 min: it stops
In object storage
Keeps its disk; its processes end.
$0.03 a GiB a month
ResumeSandbox starts it again, its files as it left them
Where to start
In numbers
- 0.15 s to start a sandbox, measured through a panel 16 ms from its server
- 0.1 s to wake a paused one, at its next call
- $0.018 an hour for 2 vCPUs and 4 GiB, by the second
- 30% of that price while it is paused
What a sandbox does
- Commands, files and a terminal. Run a command and wait for its port, edit a file by exact replacement, stream output, or open a terminal in a browser: commands and files.
- Ports. Any port at
https://<port>-<id>.<server>, public or behind a token: ports and previews. - Coding agents. Claude Code, Codex and OpenCode are installed. One call gives an agent a prompt, another streams each tool call it makes: coding agents.
- A desktop. Chrome on a 1280×800 screen, which starts at its first use: click, type and take a screenshot in one call, or watch it live: computer use.
- Templates, forks and volumes. Save a sandbox's disk and start new ones from it (templates); copy a running sandbox, memory and all, into up to 100 copies (forks); keep data on a disk outside any sandbox, on one server (volumes).
- Secrets and egress. API keys the sandbox never holds, and an allow-list of where it may connect: secrets and egress.
- SSH and observability. Plain
ssh,scpandssh -L(SSH), and each sandbox's metrics, events and usage (observability).
Agent Sandboxes and App Platform
Pethost has two kinds of workspace. App Platform is a plan's machine for your Docker Compose apps, at a flat price a month: its docs are the App Platform docs. Agent Sandboxes is what these pages are about: microVMs that your code or your agent starts, uses and stops through an API, billed by the second. Each workspace is of one kind, and one account can have both.
Every page
Start
-
How Pethost Agent Sandboxes work
What a sandbox is, its three states RUNNING, PAUSED and STOPPED, what wakes it, the two APIs, and where its memory, processes and files live.
-
Quickstart: your first sandbox
Create a sandbox, run a command, write a file, open a port and clean up: from Python, TypeScript, Go, Rust, the pethost CLI or your agent.
-
Connect an agent to sandboxes over MCP
Give Claude Code, Codex, Cursor or Claude sandboxes as tools: add the Pethost Agent Sandboxes MCP server and sign in to a workspace of sandboxes.
Concepts
-
Sandbox lifecycle: auto-pause, auto-stop and idle
When an idle sandbox pauses, stops or is deleted: what counts as activity, the three timers, keep_awake, wake_when_stopped, and values per use case.
-
Sandbox pricing and billing: per second, by state
What a sandbox costs each second it runs, pauses or sleeps, what a plan includes, free starts and their limits, the trial, and worked examples.
-
Best practices for Pethost Agent Sandboxes
The few choices that make sandboxes start fast, cost less and stay safe: templates, pausing for agents, batch jobs, keep_awake, request_id, secrets, egress.
Tasks
-
Run commands and edit files in a sandbox
Run shell commands in a sandbox and wait for their output or port, stream long ones, edit files by exact replacement, and move large files through links.
-
Ports and previews: a sandbox's URLs
Give any port of a sandbox an HTTPS address, public or behind a token, wait for a dev server to listen, and run previews that sleep between visits.
-
Run Claude Code, Codex and OpenCode in a sandbox
Give Claude Code, Codex or OpenCode a prompt in a sandbox with one call, stream its tool calls, and sign it in without the key entering the sandbox.
-
Computer use: Chrome on a desktop in a sandbox
Click, type and take a screenshot of a desktop with Chrome in one call, for a computer-use agent, or watch the sandbox's screen live in a browser.
-
Templates: start sandboxes ready to work
Save a sandbox's disk as a template, with your packages and Docker images, and start new sandboxes from it on any server in about 0.2 s.
-
Secrets and egress: keys a sandbox never holds
Give a sandbox API keys it never holds, swapped in by the egress proxy for the hosts you name, and limit where it may connect with an allow-list.
-
Fork a sandbox, memory and processes included
Copy a running sandbox, with its memory, processes and disk, into up to 100 sandboxes in one call, to try several things from the same point at once.
-
Volumes: a disk that outlives sandboxes
Create a volume, mount it into sandboxes at a path, read-write by one or read-only by many, and know where it lives and what it costs.
-
SSH into a sandbox: shell, scp, SFTP and tunnels
Sign in to any sandbox with plain ssh, copy files with scp and SFTP, and forward its ports with ssh -L, with a workspace key or a token as the password.
-
Observability: a sandbox's metrics, events and usage
Read a sandbox's CPU, memory, disk and network, list and stream its lifecycle, commands, connections, port requests and agent turns, and see what it cost.
Reference
-
Limits of Pethost Agent Sandboxes
Every bound of Pethost Agent Sandboxes in one place: sizes, plan budgets, start limits, per-sandbox and per-call limits, kept history and the network.
-
Errors of the sandboxes API, and what to do
Every refusal of the sandboxes API, its code and typed detail, what it means and what your program or agent should do next.
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.